pypa / pypa/packaging.python.org
Clarify documentation for the wheel specification
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.7k
- Forks
- 1.7k
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 4
Description
Issue Description
I find the documentation extremely hard to read and time consuming. Very badly written.
Examples:
-
In
Binary Distribution Formatsection,Detailschapter is beforeFile Formatchapter, making forward references todistribution-1.0.dist-info/WHEEL,distribution-1.0.data/. Some things are not defined at all, like what is purelib, what is patlib? -
In
Overview of the Python Packaging, there is so little about the actual source and binary packaging and so much aboutPackaging Python applications.Packaging Python applicationsis just a discussion and its place should be in a Anexa or something, and not wasting reader's time with useless information.
How should documentation be improved
- No forward references
- Be concise and precise.
- Move discussions to separate sections. There is a discussion section, but a lot of useless text for the reader is into the overview section as well.
Code of Conduct
- I am aware that participants in this repository must follow the PSF Code of Conduct.
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 with the Binary Distribution Format section, especially its Details and File Format chapters, then review Overview of the Python Packaging and Packaging Python applications. Clarify undefined terms such as purelib and platlib, remove forward references, and separate discussion from concise explanatory material. Done means the wheel documentation follows a logical order and addresses the three listed documentation goals.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100