📚 docs: reorganize using Diataxis framework#988
Conversation
gaborbernat
force-pushed
the
docs/diataxis-reorganization
branch
3 times, most recently
from
6e906fb to
e1b2b00
Compare
gaborbernat
force-pushed
the
docs/diataxis-reorganization
branch
4 times, most recently
from
2798431 to
fb091c3
Compare
Restructure documentation following the Diataxis framework with four distinct sections: tutorials for learning, how-to guides for solving problems, reference for technical details, and explanation for understanding concepts. New documentation: - tutorial/getting-started.rst - complete beginner tutorial - how-to/basic-usage.rst - common workflows and commands - how-to/config-settings.rst - backend configuration examples (addresses pypa#517) - how-to/corporate-environments.rst - proxy, SSL, private indexes (addresses pypa#725, pypa#727, pypa#409, pypa#482) - how-to/choosing-tools.rst - when to use build vs other tools (addresses pypa#268) - how-to/troubleshooting.rst - common issues and solutions - how-to/ci-cd.rst - CI/CD integration examples - reference/cli.rst - command-line interface documentation - reference/environment-variables.rst - environment variable reference - explanation/how-it-works.rst - build process internals - explanation/build-backends.rst - backend concepts and selection - development/contributing.rst - contribution guidelines Moved existing files to appropriate Diataxis sections: - installation.rst → how-to/install.rst - mission.rst → explanation/mission.rst - differences.rst → explanation/differences.rst - api.rst → reference/api.rst - test_suite.rst → development/test-suite.rst - release.rst → development/release.rst Updated conf.py to add sphinx-copybutton and sphinx-inline-tabs extensions for better documentation formatting. Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
gaborbernat
force-pushed
the
docs/diataxis-reorganization
branch
from
fb091c3 to
b29c121
Compare
gaborbernat
changed the title
- Fix API metadata example - builder.metadata doesn't exist, use metadata_path() - Clarify TMPDIR behavior - directory is cleaned up after success, persists on failure - Add note about backend availability requirement for API examples Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>
gaborbernat
force-pushed
the
docs/diataxis-reorganization
branch
from
2cf3fad to
e75ed2e
Compare
|
Just have time to review page 1: I don't like a few things about the comparisons to other tools.
So does
I'd rather this be rewritten to be something more like "build is the modern equivalent of this, but supporting any backend" (also I think we are avoiding mentioning PEPs all the time). I think I'd not mention I like comparing to other tools, but this is also 50% of the first page on build, and one key takeaway is due to standardization, all these tools do the same thing. We are "better" (sort of) than cibuildwheel might be another to compare to - that's actually different, and people do get confused on that one. |
|
Yeah a lot of them were there before, tried to update as much as I could think, but likely could do a bit more, incorporating your first round of feedback. |
Reviewer pointed out that the uv build comparison incorrectly claimed --no-isolation as a differentiator (uv has --no-build-isolation), and that the pep517.build section was unnecessary. Also suggested adding flit build and cibuildwheel comparisons since users frequently confuse these tools. Replaced --no-isolation with --config-json as a differentiator, rewrote the setup.py comparison to avoid PEP references, removed pep517.build, added flit build (sdist consistency benefit) and cibuildwheel (different tool category), and framed the section with a note that standardization means all frontends produce the same outputs.
|
Last suggestion on the difference in the main page: uv build is essentially equivalent to And the other pages: Installation: conda - I think making this tabbed, and showing mamba/micromamba/pixi would be nice. Can easily be a followup and I don't mind doing it. Basic usage: "This is equivalent to:" is wrong. It is not equivalent to that at all, though it usually produces the same outputs. The first example builds an SDist then a wheel from it, the second example builds a wheel from source instead. CI/CI: For the manual build example (and ci in general if it's installing stuff), I'd use pipx, since it's a supported package manager on all GitHub Actions images. Backend configuration: I wonder if it's worth mentioning that setuptools doesn't support Troubleshooting: No need to install wheel. Environment variables: These are pip specific. uv installer has different ones. Might be worth toggles, or a mention, or something. |
Reword uv build comparison per reviewer suggestion highlighting pip availability on systems without pre-compiled uv wheels. Fix incorrect equivalence claim between default build and --sdist --wheel (they differ: default builds wheel from sdist, explicit flags build both from source). Use pipx in CI manual example since it's pre-installed on GitHub Actions runners. Remove unnecessary wheel package from install commands. Add note that PIP_* env vars are pip-specific and link to uv's environment variables for --installer=uv users.
4 participants
This reorganization adopts the Diataxis framework to provide clear pathways for different documentation needs. 📚 The framework separates content into tutorials for learning-oriented tasks, how-to guides for problem-solving, reference material for technical specifications, and explanations for understanding core concepts. This structure helps users navigate directly to the information they need based on their current goal.
The documentation now addresses common questions identified from the issue tracker, including workflows for corporate environments with private indexes, debugging techniques using backend logs and temporary directories, and programmatic API usage patterns. Technical terms throughout link to
packaging.python.orgspecifications and Python documentation, providing context without requiring prior packaging knowledge. 🔗Documentation quality tools
docstrfmtandproselintare integrated into the build process throughtox, matching virtualenv's approach and maintaining consistent formatting and prose quality in CI. The environment variables reference has been reorganized into logical sections with descriptive introductions for common use cases like ccache integration and corporate proxy configuration.Preview: https://pypa-build--988.org.readthedocs.build/en/988/
Closes #517, #725, #727, #409, #482, #268, #438, #966, #310, #439, #655, #729, #198, #485, #640