Skip to content

📝 docs: restructure to follow Diataxis framework - #3041

Merged
gaborbernat merged 1 commit into
pypa:mainfrom
gaborbernat:docs
Feb 16, 2026
Merged

📝 docs: restructure to follow Diataxis framework#3041
gaborbernat merged 1 commit into
pypa:mainfrom
gaborbernat:docs

Conversation

@gaborbernat

@gaborbernat gaborbernat commented Feb 16, 2026

Copy link
Copy Markdown
Contributor

The virtualenv documentation was organized as a flat collection of feature-oriented pages (user_guide.rst, cli_interface.rst, installation.rst, extend.rst), making it hard for users to find what they need depending on whether they're learning, doing a task, or looking up a reference. 📚 New contributors and plugin authors had no clear starting point, and several features like PEP 440 version specifiers, free-threading support, and programmatic activation via activate_this.py were undocumented.

This restructures the entire documentation following the Diataxis framework into four quadrants — tutorials, how-to guides, reference, and explanation — plus a dedicated plugin section that itself follows the same structure. A new getting-started tutorial walks users through creating, activating, installing packages, and reproducing environments step by step. How-to guides cover installation (with uv/pipx/pip/zipapp tabs), usage patterns, and Python version selection. The reference section provides CLI flags via the existing table_cli directive, autodoc API docs, and a compatibility matrix. A single explanation page covers how virtualenv works, discovery, creators, seeders, and activators with mermaid diagrams. The plugin section adds a tutorial, task-oriented guides, API reference with autodoc, and an architecture explanation.

On the tooling side, the Sphinx theme moves to Furo with the virtualenv logo (recolored to Python blue/yellow) as the sidebar icon and SVG favicon. ✨ Extensions now include sphinx-inline-tabs for platform-specific instructions, sphinxcontrib-mermaid for diagrams, sphinx-copybutton for code blocks, and sphinxcontrib-towncrier replacing the manual changelog draft generation. A docstrfmt pre-commit hook enforces consistent RST formatting. All public plugin API classes (Discover, Creator, Seeder, Activator, AppData, PythonInfo, Session, VirtualEnvOptions) now carry full type annotations with Sphinx :param:/:returns: docstrings, enabling proper intersphinx cross-linking in the rendered docs. The ty type checker passes with zero diagnostics. Furo's search input is wired to Read the Docs Addons' search-as-you-type modal for the production site.

Old pages (user_guide.rst, cli_interface.rst, installation.rst, extend.rst) are removed — all their content has been redistributed into the new structure. The changelog switches from .. include:: _draft.rst to the towncrier-draft-entries directive. Mermaid diagram colors use a dual-theme palette (amber, blue, green, indigo, purple) that works on both light and dark backgrounds.

@gaborbernat
gaborbernat force-pushed the docs branch 3 times, most recently from fb5a23f to 200dbaa Compare February 16, 2026 09:11
@gaborbernat gaborbernat changed the title 📝 docs: restructure to follow Diátaxis framework 📝 docs: restructure to follow Diataxis framework Feb 16, 2026
The existing flat documentation layout made it hard for users to find
what they needed. Content mixed tutorials, how-to guides, reference
material, and conceptual explanations in the same pages.

Reorganized all documentation into the four Diataxis quadrants with a
dedicated plugin sub-section. Added mermaid diagrams throughout for
visual clarity, modernized Sphinx tooling (sphinxcontrib-towncrier,
sphinx-inline-tabs, sphinxcontrib-mermaid, docstrfmt), and filled
documentation gaps found by analyzing the source code (PEP 440
specifiers, free-threading, uv-managed discovery, activate_this.py,
periodic update timing, app-data caching).

Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
@gaborbernat
gaborbernat merged commit 4fb0401 into pypa:main Feb 16, 2026
0 of 2 checks passed
@gaborbernat
gaborbernat deleted the docs branch February 16, 2026 09:14
This was referenced Mar 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant