PEP 639: Update header, footer, link, reference and code block syntax #2531
Conversation
pep-0639.rst
Outdated
| Discussions-To: https://discuss.python.org/t/12622 | ||
| Status: Draft | ||
| Type: Standards Track | ||
| Content-Type: text/x-rst | ||
| Created: 15-Aug-2019 | ||
| Post-History: 15-Aug-2019, 17-Dec-2021 | ||
| Post-History: `15-Aug-2019 <https://discuss.python.org/t/2154>`__, | ||
| `17-Dec-2021 <https://discuss.python.org/t/12622>`__, |
There was a problem hiding this comment.
Do we need this final comma, or will some other tooling/CSS remove from display it later?
| `17-Dec-2021 <https://discuss.python.org/t/12622>`__, | |
| `17-Dec-2021 <https://discuss.python.org/t/12622>`__ |
There was a problem hiding this comment.
Great catch; while the linting checks in #2484 explicitly allow (but of course not require) trailing commas (for the same reasons as in Python source), I'd somehow forgotten that the build system wasn't actually automatically trimming them yet in the output. I've implemented that as part of #2467 , which is blocked on #2484 , which would suggest merging those first...but wait, the plot thickens.
As part of that, looking through the code I actually happened to notice a significant problem with allowing manual email obfuscation, which makes the automatic obfuscation not work and actually offers substantially less protection, which I discuss in #2484 (and affects this PEP, which this PR fixes). As such, that either requires a pretty complex code fix (which would take some thought and effort before its ready), or reverting part of the reversion to allow naive manual email obfuscation in the source (which would in turn require either some of the changes in this PEP, or conflicting with it). So we have a PR reference cycle, heh.
To fix this for now, I fixuped the initial commit to not add the trailing comma, as well as one other minor fix, so this should be ready now.
CAM-Gerlach
force-pushed
the
pep-639-update-rst-syntax
branch
from
376e7e8 to
0e24fc5
Compare
|
Going to go ahead with this now, since these are just technical changes and its soft-blocking #2484 |
This is part 1 in (finally) updating PEP 639 (again). This first part just makes straightforward technical changes to update the headers in line with the current guidance, take advantage of the new syntax allowed by PEP 676's implementation, prepare for moving most of the ancillary/appendix material elsewhere, and fix a handful of technical and textual issues discovered during the process.
Specifically, it uses the recommended
:ref:role for internal links, so that links (particularly cross-document ones) still work after renaming things and moving them around (among other benefits), ensures the external links are all uniformly anonymous to avoid conflicts, and strips the#from the target names to avoid confusion with footnotes or with URI fragments, and ensures the proper syntax highlighting is applied to each code block, as currently they are all over the place.This should be able to be reviewed and merged fairly quickly; the next part will contain the actual meat (principally, changing the project source metadata to use the existing
licensekey and updating the various dependent sections accordingly, plus bumping the metadata version, changinglicense_filestolicensesin.dist-info, and ensuring this PEP reflects that the original intent of PEP 621license.filewas to be read in as text as the value of theLicensefield (which was not at all initially clear from the PEP/spec, despite multiple re-reads). The final part will move the various appendices and the Rejected Ideas to separate linked auxiliary files (retaining a high-level summary of the latter in the PEP).