diff --git a/docs/source/development/build_from_source/index.rst b/docs/source/development/build_from_source/index.rst index c3202c792b..12b8cb4524 100644 --- a/docs/source/development/build_from_source/index.rst +++ b/docs/source/development/build_from_source/index.rst @@ -334,8 +334,16 @@ The CI uses ``ctest`` (see :code-file:`build-ubuntu.yml <.github/workflows/build 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. +was built for (``ISAAC_TELEOP_PYTHON_VERSION``, 3.11 by default), so install it into a virtual +environment with that version. Without one, ``pip install`` fails on Ubuntu 24.04 with +``externally-managed-environment`` and ``uv pip install`` with ``No virtual environment found``. +From the repository root: + +.. code-block:: bash + + # Replace 3.11 with your ISAAC_TELEOP_PYTHON_VERSION. --seed adds pip for the pip command below. + uv venv --python 3.11 --seed .venv + source .venv/bin/activate 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 diff --git a/docs/source/references/build.rst b/docs/source/references/build.rst index 87534e0e5a..f9b281c7dd 100644 --- a/docs/source/references/build.rst +++ b/docs/source/references/build.rst @@ -57,8 +57,10 @@ 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``, pinning the local build's version -``X.Y+local`` (``X.Y`` from the repository's ``VERSION`` file): +After building, activate a virtual environment with the build's Python version (step 4 of +:doc:`/development/build_from_source/index` shows how), then 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 @@ -80,7 +82,8 @@ In addition to the classic CMake flow above (which stages the package and produces a wheel under ``install/wheels/``), the repository ships a root :code-file:`pyproject.toml` that exposes ``isaaccapture`` through the `scikit-build-core `_ build backend, -driving the *same* top-level ``CMakeLists.txt`` (so the two paths coexist): +driving the *same* top-level ``CMakeLists.txt`` (so the two paths coexist). Run it inside an +activated virtual environment as well: .. code-block:: bash diff --git a/docs/source/teleop/quick_start.rst b/docs/source/teleop/quick_start.rst index d4b866ef53..3867e165e6 100644 --- a/docs/source/teleop/quick_start.rst +++ b/docs/source/teleop/quick_start.rst @@ -40,15 +40,31 @@ to clone the repository for a couple quick samples to run. replaces the legacy package and keeps old imports working temporarily. See :doc:`/development/migration`. -In a new terminal, activate your preferred virtual or conda environment, then install the latest -stable release from PyPI: +Install the package into a virtual environment. Without one, ``pip install`` fails on Ubuntu 24.04 +with ``externally-managed-environment`` and ``uv pip install`` with ``No virtual environment +found``. In a new terminal, from the repository root, create and activate one with +`uv `__, which downloads the requested Python if the system lacks it +(Python 3.11 to 3.13 are supported). If ``uv`` is missing, install it first as shown in +:ref:`one-time-setup`. .. code-block:: bash - pip install 'isaaccapture[cloudxr,retargeters]~=1.0' + # --seed adds pip, so plain pip install also works in this venv. + uv venv --python 3.11 --seed .venv + source .venv/bin/activate + +To use an existing venv, or a conda environment other than ``base`` (``uv`` treats ``base`` as a +system Python), activate it and skip ``uv venv``. Activate the environment again in every new +terminal you use for the steps below. + +Install the latest stable release from PyPI: + +.. code-block:: bash + + uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0' Pre-release builds are published between stable releases. Picking one up takes the NVIDIA index -and an opt-in to pre-release versions — shown here with `uv `__: +and an opt-in to pre-release versions: .. code-block:: bash