Split specifications page into multiple pages #386
Conversation
Would this result in redundant information? |
|
@pradyunsg Yes, this will "duplicate" fields in PEP 345 for a short time until we can write a new PEP which supersedes it. You might have missed that this was specifically requested in #319 (comment). |
Oh, cool then. :)
Indeed. |
There was a problem hiding this comment.
Thanks for this! It generally looks good to me, just some requested tweaks to the extracted core metadata page.
(I'm aware that external section heading links to the specifications page will now just get the spec subsection listing, but I figure navigating from there will still be easy enough, so I'm not worried about it)
| The source distribution format (``sdist``) is not currently formally defined. | ||
| Instead, its format is implicitly defined by the behaviour of the | ||
| standard library's ``distutils`` module when executing the ``setup.py sdist`` | ||
| command. |
There was a problem hiding this comment.
Given PEP 517, this section isn't quite accurate any more, but fixing that is out of scope for this PR. I've filed #388 to keep track of it.
|
|
||
| However, the version specifiers and environment markers sections of that PEP | ||
| have been superceded as described below. In addition, metadata files are | ||
| permitted to contain the following additional fields: |
There was a problem hiding this comment.
Given the change to include all the existing metadata fields as well, this intro paragraph need to be updated accordingly.
I'd also include an explicit note saying that:
- All fields added to later versions are considered optional in earlier versions (so metadata 1.3 fields can be listed even when the nominal metadata version is only 1.2)
- Metadata version 1.3 will be defined in a forthcoming PEP that also makes this URL the canonical source for the latest metadata description, so the fields listed as being added in 1.3 aren't typos, they're already-defined fields that will be included without further changes in the next version of the metadata specification
|
|
||
| .. versionadded:: 1.0 | ||
|
|
||
| Version of the file format; "1.2" is the only legal value. |
There was a problem hiding this comment.
Now that this is a multi-version format description, this should be reworded more in line with the description in PEP 416: https://www.python.org/dev/peps/pep-0426/#metadata-version
Currently permitted field values are then "1.0", "1.1", and "1.2"
|
@ncoghlan Thanks for your feedback! I think I've addressed everything. |
This should fix #319:
/specificationsis now it's own page;/specifications/core-metadata;versionaddeddirectives to metadata field specs.