Specifications page is hard to read

[dstufft]

Looking at https://packaging.python.org/specifications/ the page is kind of hard to read the current grouping doesn't seem to make much sense. It currently groups everything under either "Package distribution metadata" or "Package index interfaces", but the latter only has one item in it and the former has a bunch, some of which are only tangentially related to each other.

Perhaps it'd be best to split this up more like:

• Core Metadata
  • PEP 345
  • Provides-Extra (multiple use)
  • Description-Content-Type
• Version specifiers
• Dependency Specifiers
• Declaring Build System Dependencies
• Distribution Formats
  • Source Distribution Format
  • Binary Distribution Format
• Platform Compatibility Tags
• Recording Installed Distributions
• Simple repository API

In addition, the text for the different things kind of run together, this isn't a page you're likely to read top to bottom, but one that you're going to be looking for the specific specification you're looking for. Maybe splitting each of the top level list items into their own sub page is a better idea here? Maybe the theming discussion in #304 will make this easier to process. Perhaps using something different than different heading levels to lay out the documentation will make it easier. Maybe even this is just the best we can do!

I dunno, but the page as it stands is kind of hard to read for me.

[ddbeck]

(This is probably related to #317, too.)

Looking this page over, it seems like the "Provides-Extra" and "Description-Content-Type" sections actually have some content, while the rest are basically just cross-references to PEPs. Since there are only about ten items, it might be best to break those two sections out into their own pages, then simplify what's left into a table or list (each item being a spec name, one sentence description, and a link to the PEP or specification-specific page).

[dstufft]

I'm not real great at documentation so I can't really speak to what the best way is to do this is, but that doesn't sound unreasonable to me.

[theacodes]

Totally agreed, after #316 is done I want to revisit existing docs and file bugs for those that need lots of revision. You just got ahead of me here. 👍

I might actually make sense to split this into multiple pages, but I like your proposed structure as a starting point.

[ncoghlan]

Breaking these out into separate pages would be a good idea, as the master plan here is to change the way PyPA specifications work to be more like the way the CPython language reference works: rather than continuing to use the PEPs themselves as the specifications, instead have the specifications hosted on packaging.python.org at stable URLs (with appropriate versionadded and versionchanged notes inline), and use the PEP process to provide the rationale for changes to those specifications.

pypa/pypa.io#11 is the issue tracking that idea.

[pradyunsg]

Question: The actionable task here would be to breakout the sections of specifications page with content into separate pages and move the rest into a tabular form?

[ncoghlan]

Yeah, I think so, and with a few adjustments, I think the current headings would work reasonably well as page names:

core-metadata
version-specifiers
dependency-specifiers
declaring-build-dependencies
source-distribution-format
binary-distribution-format
platform-compatibility-tags
recording-installed-packages
simple-repository-api

For the ones that are currently just pointers to PEPs, the page could still be added, but the overview page could point directly to the relevant PEP in addition to pointing at the placeholder page.

[ncoghlan]

@di has expressed some interest in this. To break it up into more manageable chunks, I think the place to start would be to separate out the current contents of the core-metadata section to their own page at https://packaging.python.org/specifications/core-metadata/, and replace the body of the section with a link to the new page.

A follow-up commit can then bring in the contents of PEP 345 with appropriate versionadded tags (the two new fields would have .. versionadded: 1.3, and we'd follow up with a PEP formally adding those).

[ncoghlan]

The merged PR covers both the split out into multiple pages, as well as the update to have the core metadata page cover all the fields, including those that were originally defined in PEP 345.