Improve documentation

Author: chadrik

docs/quick_start/installation.rst

@@ -547,37 +547,40 @@ in a single pull request, so that regressions are not unwittingly introduced.
 
 The workflow looks like this:
 
-- Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and
-  `docker`
+- Install `uv <https://docs.astral.sh/uv/getting-started/installation/>`_ and
+  ``docker``
 - Create the temp build directory, cd into it, and run `cmake /path/to/source`
-- Run `cmake --build . --target pystubs` to generate updated stubs in
-  `src/bindings/python/stubs/__init__.pyi`
+- Run ``cmake --build . --target pystubs`` to generate updated stubs in
+  ``src/bindings/python/stubs/__init__.pyi``
 - Commit the new stubs and push to Github
-- In CI, the stubs will be included in the wheels built by `cibuildwheel`, as
-  defined in `.github/workflows/wheel_workflow.yml`
-- In CI, one of the `cibuildwheel` Github actions will rebuild the stubs to a
+- In CI, the stubs will be included in the wheels built by ``cibuildwheel``, as
+  defined in ``.github/workflows/wheel_workflow.yml``
+- In CI, one of the ``cibuildwheel`` Github actions will rebuild the stubs to a
   temp location and verify that they match what has been committed to the repo.
   This step ensures that if changes to the C++ source code and bindings results
   in a change to the stubs, developers are notified of the need to regenerate
-  the stubs, so that changes can be reviewed and the rules in `generate_stubs.py`
+  the stubs, so that changes can be reviewed and the rules in ``generate_stubs.py``
   can be updated, if necessary.
 
-Note that if you can't (or don't want to) build the stubs locally, you can
-download an artifact containing the wheel and `__init__.pyi` file from any job
-that fails the stub validation.
-
 If you want to bypass the use of docker, you can use the following steps to
-build the python bindings and run the stub generator directly:
-
-```
-python -m venv .venv
-. .venv/bin/activate
-mkdir build
-cd build
-cmake -DPython_EXECUTABLE=$(which python) -DCMAKE_INSTALL_PREFIX=../dist ..
-cmake --build . --target=install
-# extract the deps from the pyproject.toml and install them
-pip install $(yq -r '.tool.cibuildwheel.overrides.[0].test-requires' -oy ../pyproject.toml)
-PY_VER=$(python -c "import sys;print(f'{sys.version_info[0]}.{sys.version_info[1]}')")
-PYTHONPATH=../dist/lib/python$PY_VER/site-packages python ../src/bindings/python/stubs/generate_stubs.py --out-path ../src/bindings/python/stubs/
-```
+build the python bindings and run the stub generator directly (requires python
+3.11+):
+
+.. code-block:: bash
+
+    python -m venv .venv
+    . .venv/bin/activate
+    mkdir build
+    cd build
+    cmake -DPython_EXECUTABLE=$(which python) -DCMAKE_INSTALL_PREFIX=../dist ..
+    cmake --build . --target=install
+    # extract the deps from the pyproject.toml and install them into the virtualenv
+    PY_DEPS=$(python -c "import tomllib;print(tomllib.load(open('../pyproject.toml', 'rb'))['tool']['cibuildwheel']['overrides'][0]['test-requires'])")
+    pip install ${PY_DEPS}
+    PY_VER=$(python -c "import sys;print(f'{sys.version_info[0]}.{sys.version_info[1]}')")
+    # generate stubs
+    PYTHONPATH=../dist/lib/python$PY_VER/site-packages python ../src/bindings/python/stubs/generate_stubs.py
+
+If all else fails and you can't build the stubs locally, you can push changes
+to CI and download an artifact containing the wheel and ``__init__.pyi`` file from
+any job that fails the stub validation.

src/bindings/python/stubs/generate_stubs.py

@@ -29,14 +29,31 @@
 
 class OCIOSignatureGenerator(AdvancedSignatureGenerator):
     sig_matcher = AdvancedSigMatcher(
+        # Override entire function signature:
         signature_overrides={
             # signatures for these special methods include many inaccurate overloads
             "*.__ne__": "(self, other: object) -> bool",
             "*.__eq__": "(self, other: object) -> bool",
         },
+        # Override argument types
         arg_type_overrides={
+            # (name_pattern, arg, type): arg_type
+            # type can be str | re.Pattern
             ("*", "*", re.compile(r"list\[(.*)]")): r"Iterable[\1]",
         },
+        # Override result types
+        #   dict of (name_pattern, type) to result_type
+        #   e.g. ("*", "Buffer"): "numpy.ndarray"
+        result_type_overrides={},
+        # Override property types
+        #   dict of (name_pattern, type) to result_type
+        #   e.g. ("*", "Buffer"): "numpy.ndarray"
+        property_type_overrides={},
+        # Types that have implicit alternatives.
+        #   dict of type_str to list of types that can be used instead
+        #   e.g. "PySide2.QtGui.QKeySequence": ["str"],
+        # converts any matching argument to a union of the supported types
+        implicit_arg_types={},
     )
 
     def process_sig(