🍒 [release/1.6.x] docs(build): install the local wheel by path instead of --no-index

docs/source/development/build_from_source/index.rst

@@ -331,33 +331,27 @@ The CI uses ``ctest`` (see :code-file:`build-ubuntu.yml <.github/workflows/build
 4. Install the ``isaaccapture`` pip package
 -------------------------------------------
 
-The wheels are built in the ``./install/wheels/`` directory. Install the package from the wheels.
-Using ``pip``, you need to pass the ``--no-index`` option to automatically find the right wheel
-based on the Python version.  Note that ``pip`` and ``uv pip`` has slightly different options.
+The build writes two wheels to ``./install/wheels/``: ``isaaccapture`` and the ``isaacteleop``
+transition wheel it depends on. The ``isaaccapture`` wheel only installs on the Python version it
+was built for (``ISAAC_TELEOP_PYTHON_VERSION``, 3.11 by default), so create and activate a venv
+with that version first.
+
+Install it by version. A local build is always ``X.Y+local``, where ``X.Y`` is the first two
+numbers of the repository's ``VERSION`` file; they also appear in the wheel's file name. The pin
+selects your build for the venv's Python, so a newer published ``isaaccapture`` cannot replace it.
+``--find-links`` supplies the ``isaacteleop`` transition wheel and the other dependencies come
+from the package index, so do not add ``--no-index``. The two tools name the reinstall option
+differently:
 
 .. code-block:: bash
 
-   # Pass --no-index to use only wheels in ./install/wheels/;
-   # Pass --force-reinstall to replace an existing install.
-   pip install "isaaccapture[retargeters,cloudxr,ui]" --find-links=./install/wheels/ --no-index --force-reinstall
-
-With ``uv pip``, ``--find-links`` still consults the package index and installs the highest
-version it finds, so a newer published ``isaaccapture`` there silently wins over your local build.
-``--no-index`` is not a fix either: the wheel's dependencies are not in ``./install/wheels/``, so
-the install fails. Install the local wheel by path instead. That always selects your build, while
-the index stays available for its dependencies:
+   # Replace X.Y with your build's version. --force-reinstall replaces an existing install.
+   pip install "isaaccapture[retargeters,cloudxr,ui]==X.Y+local" --find-links=./install/wheels/ --force-reinstall
 
 .. code-block:: bash
 
-   # Pick the wheel for your Python version (cp312 = Python 3.12; use cp311 or cp313 otherwise).
-   # -t sorts by modification time so head -1 selects the most recent build if older wheels remain.
-   WHEEL=$(ls -t ./install/wheels/isaaccapture-*-cp312-*.whl | head -1)
-
    # --reinstall-package replaces an already-installed isaaccapture, e.g. after a rebuild.
-   # --find-links exposes the sibling isaacteleop transition wheel built alongside isaaccapture.
-   uv pip install "${WHEEL}[retargeters,cloudxr,ui]" --find-links=./install/wheels/ --reinstall-package isaaccapture
-
-Check that the installed version ends in ``+local`` with ``uv pip list | grep isaaccapture``.
+   uv pip install "isaaccapture[retargeters,cloudxr,ui]==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
 
 The wheel carries the ``isaacteleop`` compatibility alias, which will be removed
 in 1.9, so

docs/source/references/build.rst

@@ -57,18 +57,17 @@ The project uses a modern CMake target-based approach. Libraries export namespac
 Using the Python wheel
 ----------------------
 
-After building, install the wheels with ``uv`` or ``pip``:
+After building, install the wheels with ``uv`` or ``pip``, pinning the local build's version
+``X.Y+local`` (``X.Y`` from the repository's ``VERSION`` file):
 
 .. code-block:: bash
 
-   # Install the wheel by path so a newer release on the index cannot win over the local build
-   # (cp312 = Python 3.12). -t/head -1 picks the newest build if older wheels remain in the dir.
-   WHEEL=$(ls -t ./install/wheels/isaaccapture-*-cp312-*.whl | head -1)
+   # The pin keeps a newer release on the index from winning over the local build.
    # --find-links exposes the sibling isaacteleop transition wheel built alongside isaaccapture.
-   uv pip install "${WHEEL}" --find-links=./install/wheels/ --reinstall-package isaaccapture
+   uv pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
 
    # or
-   pip install install/wheels/isaaccapture-*.whl
+   pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/
 
 The wheel carries the ``isaacteleop`` compatibility alias, which will be removed
 in 1.9, so