📝 docs: restructure to follow Diataxis framework - #3041
Merged
Conversation
gaborbernat
force-pushed
the
docs
branch
3 times, most recently
from
February 16, 2026 09:11
fb5a23f to
200dbaa
Compare
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>
This was referenced Mar 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 viaactivate_this.pywere 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/zipapptabs), usage patterns, and Python version selection. The reference section provides CLI flags via the existingtable_clidirective, 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-tabsfor platform-specific instructions,sphinxcontrib-mermaidfor diagrams,sphinx-copybuttonfor code blocks, andsphinxcontrib-towncrierreplacing the manual changelog draft generation. Adocstrfmtpre-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. Thetytype 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.rstto thetowncrier-draft-entriesdirective. Mermaid diagram colors use a dual-theme palette (amber, blue, green, indigo, purple) that works on both light and dark backgrounds.