docs: reorganize documentation following Diátaxis framework#970
Merged
mergify[bot] merged 4 commits intopython-wheel-build:mainfrom Mar 21, 2026
Merged
Conversation
Create dedicated reference documentation section to improve discoverability of CLI, configuration, and file format documentation. Changes: - Create docs/reference/ directory with landing page - Move reference files: cli.rst, config-reference.rst, hooks.rst, files.md, glossary.rst to reference/ - Reorganize main index with clear Diátaxis framework sections: * Getting Started (quickstart, getting-started) * Guides (how-tos, customization, using) * Concepts & Explanation (concepts, http-retry) * Reference (new reference section) * Development (develop) - Update all cross-references to moved files - Add Quick Reference section to reference/index.rst for common lookups Impact: Reference material now discoverable in ≤2 clicks from main index Related: python-wheel-build#969 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Reorganize how-to guides with clear categories and popular guides section for improved discoverability. Changes: - Add "Popular Guides" section with links to most common tasks - Categorize guides into logical groups: * Getting Started: containers, bootstrap-constraints * Building Packages: git repos, repeatable builds, parallel, web server * Build Configuration: pyproject overrides, multiple versions, pre-releases * Analyzing Builds: graph commands - Add descriptive text explaining guide categories - Add "See Also" section linking to customization and reference docs Impact: Users can quickly scan categories and find relevant guides Related: python-wheel-build#969 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add "Next Steps" and "See Also" sections to key pages to help users discover related content and navigate naturally between topics. Changes: - Enhanced quickstart.rst with categorized next steps (Learn More, Common Tasks, Customize Builds) - Added next steps to getting-started.rst linking to containers, constraints, customization, and concepts - Added "See Also" section to customization.md with links to reference docs and related how-tos - Added "See Also" section to using.md with links to concepts and how-to guides - Enhanced concepts/index.rst with overview, related guides, and reference links Impact: Users can naturally flow from one topic to related topics Related: python-wheel-build#969 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
dhellmann
force-pushed
the
docs/reorganize-documentation
branch
from
f9801ba to
7ce6858
Compare
tiran
approved these changes
Mar 21, 2026
Collaborator
tiran
left a comment
tiran
left a comment
There was a problem hiding this comment.
LGTM! Thanks for the docs improvements
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
2 participants
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.
Summary
This PR reorganizes the fromager documentation to improve discoverability and navigation, implementing the plan from #969.
Changes Made
Phase 1: Create Reference Section
/docs/reference/directory with landing pagePhase 3: Enhanced How-To Navigation
Phase 4: Add Cross-References
Phase 5: Testing and Validation
Impact
Before: Reference material scattered at root level, how-to guides hidden under single toctree entry
After: Clear Diátaxis framework with dedicated reference section, categorized how-tos, extensive cross-linking
Users can now:
Files Changed
docs/reference/Test Plan
Closes #969
🤖 Generated with Claude Code