pypa / pypa/packaging.python.org
Separate PyPA specifications from user guide
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.7k
- Forks
- 1.7k
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 4
Description
https://packaging.python.org/ is currently titled Python Packaging User Guide and contains both information targeted towards Python developers (tutorials, guides and discussions) as well as the specifications maintained by the PyPA targeted towards Python package tooling developers. For some topics the site has pages for both perspectives, e.g. there's the Writing your pyproject.toml guide and the pyproject.toml specification.
I see two issues with the current setup for users: 1) it's very easy to stumble into the specification section when using the search and 2) guides and specifications visually look the same (you have to look at either the sidebar or the URL path to identify where you are).
For example, see what currently happens when a user searches for "virtual environment":
The third result here seems to be the most comprehensive since it's a page titled Python Virtual Environments, however that link will actually take you to the Python Virtual Environments specification, which isn't really helpful for users trying to learn about virtual environments.
Even when a user guide exists, the search currently sometimes yields a wrong first result. Searching for "writing pyproject.toml" yields pyproject.toml specification as the first result and Writing your pyproject.toml only as the 3rd result.
While the latter could be fixed by prioritizing title matches, the former doesn't seem to be easily solvable with both sections living in the Sphinx site. So I think you should consider moving the PyPA specifications to a separate site (perhaps pypa.io or a different subdomain).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the current Sphinx site structure, including the guides and specifications sections, and reproduce the linked search examples. The issue does not name a file or test; consider the separation options and document what a completed migration would require for users to distinguish and find specifications reliably.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100