.. _docs-system-tooling-python-environments:


######################################################################
Python Environments
######################################################################

How the Documentation System manages Python versions and per-repo
virtualenvs using ``pyenv`` + ``pyenv-virtualenv``. Every doc repo
has its own isolated environment so extension upgrades in one repo
never break another.

.. meta::
   :keywords: pyenv, virtualenv, python, docs-env.sh
   :audience: brad, ai-agents
   :last-reviewed: |date|
   :summary: pyenv + pyenv-virtualenv workflow for doc repos, including
      docs-env.sh automation and the naming convention.

.. |date| date:: %m/%d/%Y


**********************************************************************
Architecture
**********************************************************************

.. _docs-system-tooling-python-environments-architecture:

.. graphviz::

   digraph envs {
       rankdir=LR
       node [shape=box fontsize=11]
       versions_yml [label="versions.yml\n(baseline pin)" shape=note]
       python_version [label=".python-version\n(per-repo)" shape=note]
       requirements [label="requirements-docs.txt\n(per-repo)" shape=note]

       versions_yml -> python_version [label="declares baseline"]
       python_version -> pyenv [label="pyenv reads"]
       pyenv -> virtualenv [label="creates"]
       requirements -> virtualenv [label="pip install -r"]

       pyenv [label="pyenv\n3.13.1"]
       virtualenv [label="docs-{slug}\nvirtualenv"]
   }

- ``versions.yml`` declares the fleet-wide baseline Python version.
- Each repo's ``.python-version`` pins that version (or an override).
- Each repo has a ``docs-{slug}`` pyenv virtualenv named after its
  canonical project slug.
- ``requirements-docs.txt`` pins Sphinx + all mandatory/per-repo
  extensions into the virtualenv.


**********************************************************************
The ``docs-env.sh`` Wrapper
**********************************************************************

.. _docs-system-tooling-python-environments-docs-env:

The ``docs-env.sh`` script at ``~/.local/bin/`` automates the full
lifecycle. It reads ``repos.conf`` to resolve the current directory
to a project slug, then manages the corresponding virtualenv.

.. code-block:: bash

   # Create the virtualenv + install deps (run once per repo)
   docs-env.sh create

   # Activate in current shell
   eval "$(docs-env.sh activate)"

   # Re-install deps after a version bump
   docs-env.sh sync

   # Show current virtualenv state
   docs-env.sh status

   # List all doc-system virtualenvs
   docs-env.sh list

The ``make env`` target in every repo's Makefile calls
``docs-env.sh create`` automatically.


**********************************************************************
Virtualenv Naming Convention
**********************************************************************

.. _docs-system-tooling-python-environments-naming:

Every doc-system virtualenv is named ``docs-{slug}`` where ``{slug}``
is the repo's canonical project slug from
:ref:`docs-system-reference-repo-registry`:

.. list-table::
   :header-rows: 1
   :widths: 30 25 45

   * - Repo
     - Slug
     - Virtualenv name
   * - Documentation_System
     - ``docs-system``
     - ``docs-docs-system``
   * - Linux
     - ``linux-docs``
     - ``docs-linux-docs``
   * - DevOps-Docs
     - ``devops-docs``
     - ``docs-devops-docs``
   * - Artificial-Intelligence
     - ``ai-docs``
     - ``docs-ai-docs``
   * - Server_Programs
     - ``server-programs``
     - ``docs-server-programs``
   * - Accounting
     - ``accounting-docs``
     - ``docs-accounting-docs``
   * - Entrepreneurship
     - ``entrepreneurship-docs``
     - ``docs-entrepreneurship-docs``


**********************************************************************
Manual pyenv Commands (Reference)
**********************************************************************

.. _docs-system-tooling-python-environments-manual:

When ``docs-env.sh`` is unavailable, use these commands directly.

.. code-block:: bash

   # List all installed Python versions
   pyenv versions

   # List all versions available to install
   pyenv install -l

   # Install a specific version
   pyenv install 3.13.1

   # Create a virtualenv
   pyenv virtualenv 3.13.1 docs-linux-docs

   # Activate a virtualenv
   pyenv activate docs-linux-docs

   # Set the local Python version for a directory
   pyenv local 3.13.1

   # Set the global default Python version
   pyenv global 3.13.1

   # Remove a virtualenv
   pyenv uninstall docs-linux-docs

   # Export installed packages
   pip freeze > requirements.txt

   # Install from requirements file
   pip install -r requirements-docs.txt


**********************************************************************
Troubleshooting
**********************************************************************

.. _docs-system-tooling-python-environments-troubleshooting:

**"version X is not installed"** when entering a repo directory:

   The ``.python-version`` file requests a Python version that pyenv
   hasn't installed yet. Run ``pyenv install <version>`` or
   ``docs-env.sh create`` to install it.

**OpenSSL version mismatch** when compiling older Python:

   Python < 3.5.3 requires OpenSSL 1.0.x. Modern systems ship
   OpenSSL 3.x. If you must compile an older Python, point the build
   at an older OpenSSL library. For the doc-system fleet (Python
   3.13.1), this is not an issue.

**"externally-managed-environment" error** from pip:

   You're running pip against the system Python, not the pyenv
   virtualenv. Activate the virtualenv first
   (``eval "$(docs-env.sh activate)"``) or use the full path:
   ``~/.pyenv/versions/docs-{slug}/bin/pip install ...``


**********************************************************************
Links and References
**********************************************************************

.. _docs-system-tooling-python-environments-references:

- `pyenv GitHub repository <https://github.com/pyenv/pyenv>`_
- `pyenv-virtualenv plugin <https://github.com/pyenv/pyenv-virtualenv>`_
- `What is the difference between venv, pyvenv, pyenv, virtualenv, virtualenvwrapper, pipenv, etc? <https://stackoverflow.com/questions/41573587/what-is-the-difference-between-venv-pyvenv-pyenv-virtualenv-virtualenvwrappe>`_