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.

Architecture

$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

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.

# 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

Every doc-system virtualenv is named docs-{slug} where {slug} is the repo’s canonical project slug from Repository Registry:

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)

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

# 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

“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 ...