You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
While it can't get us back the substantial hassle of having to finagle the includes/excludes to fix the many issues that dumping all the PEPs in the root directory and naming many of them .txt instead of .rst has caused us in the past (e.g. #2423 , #2405 , #2264 , and parts of several others), it will certainly help avoid any future issues going forward, and allow us to re-simplify the custom config and plugins/hacks we have in place to deal with this. Additionally, it adds a time and complexity cost to everyday grepping as well as finding/scrolling through all the PEP files in the root to find the few important non-PEP ones. Also, its caused a fair amount of confusion in the past, since its ambiguous whether arbitrary non-PEP files in the root are meta-documentation/build scripts/config/etc. at the repo level, or are associated with individual PEPs.
Given that now the main reasons for not doing this (chiefly, GitHub not tracking moves) are no longer an issue (several other things surrounding this have been improved as well), I'm 👍 on this change (moving all the PEPs to a peps subdir with a consistent .rst extension, and am willing to help make it happen (we'd need to tweak the makefile and build config, update the path in the linting checks, and make sure everything still works).
To note, that was already completed many years ago and all the PEPs are using reST syntax internally, just that the old PEPs still used the .txt extension (#4) for historical reasons, which are now no longer relevant as you mention.
I don't remember where, but someone made the point that for PEPs, the text files are the project, rather than in support of the project, as is the case with standard documentation.
I'd be in favour of cleaning up the ancialliary files where possible, but I don't think we should move the files, even if we can.
Even so, many projects have their main project files under a subdirectory, for example src/project_name or project_name, and tests and other stuff elsewhere.
Even so, many projects have their main project files under a subdirectory, for example src/project_name or project_name, and tests and other stuff elsewhere.
Indeed, that's pretty much all Python projects, many of which have the tests inline with the code in the subdir rather than under another subdirectory, along with many (most) other languages (e.g. src), and even on the various docs projects I contribute to, very often the docs are still in a docs subdir, even if the top-level repo is just docs. Same with e.g. static sites, which typically include all content in a content or similar subdir, even if there are minimal supporting files.
That line of argument sounds a bit philosophical, but the point being discussed here is purely a practical matter due to the current code host in use.
Indeed; practicality over purity. The reasons advanced for the move are essentially all practical in nature, namely:
Creates a clean, clear separation between PEP content and non-PEP files for humans and tools that doesn't require parsing filename patterns
Allows us to simplify the config and custom Sphinx filtering code that is currently required to deal with this and avoiding issues in the future similar to the many we've had to deal with in the past
Makes the readme, meta-documentation, build scripts, etc. much easier to find and navigate to, on GitHub and locally
Reduces the time/complexity cost to everyday grepping, globbing and searching
Easier to understand and less overwhelming to newer PEP authors
Therefore, if we're going to move anything anyway (which git doesn't care if its a rename or a move), we may as well just do things properly at the same time to really get the benefit of it.
@CAM-Gerlach, I would like to help transition all PEPs from .txt to .rst, moving them into a common subdir, etc, by creating a PR, just as @timofurrer attempted in 2016 via timofurrer@b6afc70.
Anybody else working on this currently?
How can collaboration be organized for this issue?
The actual move (and rename of the PEPs to .rst) is fairly trivial for any of us to do; there are a handful of other things that need to be updated/simplified afterward, but realistically that's best (and most easily) done by a PEP editor familiar with all the infrastructure involved, assuming we decide to actually go ahead with it.
However, there are a number of tasks to fix outstanding technical/editorial defects that you could help with right now with relatively that should be much more achievable, helpful to use and beneficial to PEP readers and authors, such as:
Fixing the remaining docutils/Sphinx warnings
Adding the necessary lexer tags to non-Python code blocks on old PEPs so they are syntax-highlighted correctly
Adding missing URLs to the discussions-to, post history and resolution headers
Repairing broken external links, and fixing any other clear defects
To note, we don't generally suggest opening big PRs doing the same thing to a bunch of PEPs, especially as a newer contributor. Instead, a good approach to this is to pick one PEP that has at least one build warning, fix that and each of the other technical issues present (one type of fix per commit), and then submit that as a PR for review. See, e.g. #2751, #2754 or any of Hugo's other similar PRs for examples.
I plan to open a meta-issue (hopefully later today; I've already written up a lot of it) documenting this approach and tracking the main remaining defect-fixing tasks that have value and meet the criteria, with a particular eye toward making it straightforward for any contributor to help with. Keep an eye out for that if you're interested in helping out. Thanks!
pep-0593.rst:265: WARNING: Citation [struct-doc] is not referenced.
pep-0593.rst:265: WARNING: duplicate citation mypy, other instance in pep-0484.txt
pep-0593.rst:271: WARNING: duplicate citation pycharm, other instance in pep-0482.txt
pep-0484.txt:2490: WARNING: Citation [peps] is not referenced.
pep-0484.txt:2463: WARNING: duplicate citation mypy, other instance in pep-0482.txt
pep-0484.txt:2475: WARNING: duplicate citation pyflakes, other instance in pep-0482.txt
pep-0484.txt:2478: WARNING: duplicate citation pylint, other instance in pep-0482.txt
pep-0520.txt:416: WARNING: Citation [nick_concern] is not referenced.
pep-0520.txt:419: WARNING: Citation [orig] is not referenced.
pep-0520.txt:422: WARNING: Citation [followup1] is not referenced.
pep-0520.txt:425: WARNING: Citation [followup2] is not referenced.
pep-0554.rst:1709: WARNING: Citation [nathaniel-asyncio] is not referenced.
pep-0554.rst:1712: WARNING: Citation [extension-docs] is not referenced.
pep-0554.rst:1645: WARNING: Citation [CSP] is not referenced.
pep-0554.rst:1677: WARNING: Citation [mp-conn] is not referenced.
pep-0554.rst:1686: WARNING: Citation [main-thread] is not referenced.
pep-0553.rst:283: WARNING: Citation [envar] is not referenced.
pep-0661.rst:323: WARNING: Footnote [5] is not referenced.
pep-0661.rst:324: WARNING: Footnote [6] is not referenced.
pep-0661.rst:325: WARNING: Footnote [7] is not referenced.
pep-0661.rst:326: WARNING: Footnote [8] is not referenced.
pep-0538.txt:1181: WARNING: Footnote [1] is not referenced.
pep-0538.txt:1184: WARNING: Footnote [2] is not referenced.
pep-0538.txt:1187: WARNING: Footnote [3] is not referenced.
pep-0538.txt:1190: WARNING: Footnote [4] is not referenced.
pep-0538.txt:1193: WARNING: Footnote [5] is not referenced.
pep-0538.txt:1196: WARNING: Footnote [6] is not referenced.
pep-0538.txt:1199: WARNING: Footnote [7] is not referenced.
pep-0538.txt:1202: WARNING: Footnote [8] is not referenced.
pep-0538.txt:1205: WARNING: Footnote [9] is not referenced.
pep-0538.txt:1208: WARNING: Footnote [10] is not referenced.
pep-0538.txt:1211: WARNING: Footnote [11] is not referenced.
pep-0538.txt:1214: WARNING: Footnote [12] is not referenced.
pep-0538.txt:1217: WARNING: Footnote [13] is not referenced.
pep-0538.txt:1220: WARNING: Footnote [14] is not referenced.
pep-0538.txt:1223: WARNING: Footnote [15] is not referenced.
pep-0538.txt:1226: WARNING: Footnote [16] is not referenced.
pep-0538.txt:1229: WARNING: Footnote [17] is not referenced.
pep-0538.txt:1232: WARNING: Footnote [18] is not referenced.
pep-0538.txt:1235: WARNING: Footnote [19] is not referenced.
pep-0538.txt:1238: WARNING: Footnote [20] is not referenced.
pep-0538.txt:1241: WARNING: Footnote [21] is not referenced.
pep-0538.txt:1244: WARNING: Footnote [22] is not referenced.
pep-0501.txt:557: WARNING: Footnote [#] is not referenced.
pep-0501.txt:560: WARNING: Footnote [#] is not referenced.
pep-0501.txt:563: WARNING: Footnote [#] is not referenced.
pep-0501.txt:566: WARNING: Footnote [#] is not referenced.
pep-0501.txt:568: WARNING: Footnote [#] is not referenced.
pep-0501.txt:570: WARNING: Footnote [#] is not referenced.
pep-0501.txt:572: WARNING: Footnote [#] is not referenced.
pep-0501.txt:574: WARNING: Footnote [#] is not referenced.
pep-0501.txt:577: WARNING: Footnote [#] is not referenced.
pep-0501.txt:580: WARNING: Footnote [#] is not referenced.
pep-0432.txt:1381: WARNING: Footnote [1] is not referenced.
pep-0432.txt:1384: WARNING: Footnote [2] is not referenced.
pep-0432.txt:1387: WARNING: Footnote [3] is not referenced.
pep-0432.txt:1390: WARNING: Footnote [4] is not referenced.
pep-0432.txt:1393: WARNING: Footnote [5] is not referenced.
pep-0432.txt:1396: WARNING: Footnote [6] is not referenced.
pep-0432.txt:1399: WARNING: Footnote [7] is not referenced.
pep-0432.txt:1403: WARNING: Footnote [8] is not referenced.
pep-0432.txt:1406: WARNING: Footnote [9] is not referenced.
pep-0432.txt:1409: WARNING: Footnote [10] is not referenced.
pep-0642.rst:1835: WARNING: Footnote [1] is not referenced.
pep-0642.rst:1838: WARNING: Footnote [2] is not referenced.
pep-0642.rst:1841: WARNING: Footnote [3] is not referenced.
pep-0642.rst:1844: WARNING: Footnote [4] is not referenced.
pep-0642.rst:1847: WARNING: Footnote [5] is not referenced.
pep-0642.rst:1850: WARNING: Footnote [6] is not referenced.
pep-0642.rst:1853: WARNING: Footnote [7] is not referenced.
pep-0642.rst:1856: WARNING: Footnote [8] is not referenced.
pep-0642.rst:1859: WARNING: Footnote [9] is not referenced.
pep-0634.rst:140: WARNING: duplicate label guards, other instance in pep-0622.rst
pep-0634.rst:175: WARNING: duplicate label patterns, other instance in pep-0622.rst
pep-0634.rst:231: WARNING: duplicate label literal_pattern, other instance in pep-0622.rst
pep-0634.rst:267: WARNING: duplicate label capture_pattern, other instance in pep-0622.rst
pep-0634.rst:290: WARNING: duplicate label wildcard_pattern, other instance in pep-0622.rst
pep-0634.rst:337: WARNING: duplicate label sequence_pattern, other instance in pep-0622.rst
pep-0634.rst:417: WARNING: duplicate label mapping_pattern, other instance in pep-0622.rst
pep-0634.rst:472: WARNING: duplicate label class_pattern, other instance in pep-0622.rst
pep-0634.rst:598: WARNING: duplicate label appendix a, other instance in pep-0622.rst
pep-0601.txt:223: WARNING: Footnote [1] is not referenced.
pep-0601.txt:225: WARNING: Footnote [2] is not referenced.
pep-0601.txt:227: WARNING: Footnote [3] is not referenced.
pep-0601.txt:229: WARNING: Footnote [4] is not referenced.
pep-0601.txt:231: WARNING: Footnote [5] is not referenced.
pep-0601.txt:233: WARNING: Footnote [6] is not referenced.
pep-0601.txt:235: WARNING: Footnote [7] is not referenced.
pep-0601.txt:237: WARNING: Footnote [8] is not referenced.
pep-0601.txt:239: WARNING: Footnote [9] is not referenced.
pep-0565.rst:337: WARNING: Footnote [1] is not referenced.
pep-0565.rst:340: WARNING: Footnote [2] is not referenced.
pep-0565.rst:343: WARNING: Footnote [3] is not referenced.
pep-0565.rst:346: WARNING: Footnote [4] is not referenced.
pep-0565.rst:349: WARNING: Footnote [5] is not referenced.
pep-0565.rst:352: WARNING: Footnote [6] is not referenced.
pep-0565.rst:355: WARNING: Footnote [7] is not referenced.
pep-0565.rst:358: WARNING: Footnote [8] is not referenced.
pep-0565.rst:361: WARNING: Footnote [9] is not referenced.
pep-0635.rst:403: WARNING: duplicate label patterns, other instance in pep-0634.rst
pep-0635.rst:592: WARNING: duplicate label literal_pattern, other instance in pep-0634.rst
pep-0635.rst:681: WARNING: duplicate label capture_pattern, other instance in pep-0634.rst
pep-0635.rst:740: WARNING: duplicate label wildcard_pattern, other instance in pep-0634.rst
pep-0635.rst:907: WARNING: duplicate label sequence_pattern, other instance in pep-0634.rst
pep-0635.rst:967: WARNING: duplicate label mapping_pattern, other instance in pep-0634.rst
pep-0635.rst:1014: WARNING: duplicate label class_pattern, other instance in pep-0634.rst
pep-0605.rst:1346: WARNING: Footnote [1] is not referenced.
pep-0605.rst:1349: WARNING: Footnote [2] is not referenced.
pep-0605.rst:1352: WARNING: Footnote [3] is not referenced.
pep-0605.rst:1355: WARNING: Footnote [4] is not referenced.
pep-0605.rst:1358: WARNING: Footnote [5] is not referenced.
pep-0605.rst:1361: WARNING: Footnote [6] is not referenced.
pep-0550.rst:1704: WARNING: Footnote [4] is not referenced.
pep-0550.rst:1718: WARNING: Footnote [11] is not referenced.
pep-0550.rst:1720: WARNING: Footnote [13] is not referenced.
pep-0550.rst:1722: WARNING: Footnote [14] is not referenced.
pep-0550.rst:1724: WARNING: Footnote [15] is not referenced.
pep-0550.rst:1726: WARNING: Footnote [16] is not referenced.
pep-0467.txt:239: WARNING: Footnote [1] is not referenced.
pep-0467.txt:241: WARNING: Footnote [2] is not referenced.
pep-0467.txt:243: WARNING: Footnote [3] is not referenced.
pep-0467.txt:245: WARNING: Footnote [4] is not referenced.
pep-0467.txt:247: WARNING: Footnote [5] is not referenced.
pep-0467.txt:249: WARNING: Footnote [6] is not referenced.
pep-0558.rst:1299: WARNING: Footnote [2] is not referenced.
pep-0558.rst:1323: WARNING: Footnote [10] is not referenced.
pep-0558.rst:1326: WARNING: Footnote [11] is not referenced.
pep-0558.rst:1329: WARNING: Footnote [12] is not referenced.
pep-0558.rst:1332: WARNING: Footnote [13] is not referenced.
pep-0532.txt:886: WARNING: Footnote [1] is not referenced.
pep-0532.txt:889: WARNING: Footnote [2] is not referenced.
pep-0532.txt:892: WARNING: Footnote [3] is not referenced.
pep-0577.rst:806: WARNING: Footnote [1] is not referenced.
pep-0577.rst:809: WARNING: Footnote [2] is not referenced.
pep-0577.rst:812: WARNING: Footnote [3] is not referenced.
pep-0577.rst:815: WARNING: Footnote [4] is not referenced.
pep-0598.rst:885: WARNING: Footnote [1] is not referenced.
pep-0598.rst:888: WARNING: Footnote [2] is not referenced.
pep-0598.rst:891: WARNING: Footnote [3] is not referenced.
pep-3150.txt:753: WARNING: Footnote [5] is not referenced.
pep-3150.txt:768: WARNING: Footnote [10] is not referenced.
pep-0531.txt:640: WARNING: Footnote [6] is not referenced.
pep-0535.txt:182: WARNING: Footnote [1] is not referenced.
pep-0440.txt:1559: WARNING: Footnote [1] is not referenced.
pep-0440.txt:1565: WARNING: Footnote [3] is not referenced.
pep-0440.txt:1583: WARNING: Footnote [9] is not referenced.
pep-0430.txt:208: WARNING: Footnote [1] is not referenced.
pep-0430.txt:211: WARNING: Footnote [2] is not referenced.
pep-0430.txt:214: WARNING: Footnote [3] is not referenced.
pep-0395.txt:727: WARNING: Footnote [4] is not referenced.
pep-0366.txt:136: WARNING: Footnote [4] is not referenced.
pep-0231.txt:616: WARNING: Footnote [8] is not referenced.
pep-0003.txt:72: WARNING: Footnote [1] is not referenced.
Remaining warnings
pep-0262.txt:318: WARNING: Footnote [1] is not referenced.
pep-0277.txt:106: WARNING: Footnote [1] is not referenced.
pep-0292.txt:201: WARNING: Footnote [3] is not referenced.
pep-0292.txt:206: WARNING: Footnote [5] is not referenced.
pep-0299.txt:112: WARNING: Footnote [1] is not referenced.
pep-0323.txt:478: WARNING: Footnote [1] is not referenced.
pep-0323.txt:481: WARNING: Footnote [2] is not referenced.
pep-0326.txt:448: WARNING: Footnote [5] is not referenced.
pep-0326.txt:458: WARNING: Footnote [8] is not referenced.
pep-0326.txt:466: WARNING: Footnote [11] is not referenced.
pep-0329.txt:258: WARNING: Footnote [2] is not referenced.
pep-0336.txt:122: WARNING: Footnote [1] is not referenced.
pep-0232.txt:250: WARNING: Footnote [3] is not referenced.
pep-0340.txt:566: WARNING: Footnote [1] is not referenced.
pep-0343.txt:956: WARNING: Footnote [12] is not referenced.
pep-0355.txt:549: WARNING: Footnote [1] is not referenced.
pep-0361.txt:273: WARNING: Footnote [1] is not referenced.
pep-0370.txt:219: WARNING: Footnote [6] is not referenced.
pep-0371.txt:420: WARNING: Footnote [6] is not referenced.
pep-0371.txt:427: WARNING: Footnote [8] is not referenced.
pep-3115.txt:300: WARNING: Footnote [1] is not referenced.
pep-3115.txt:303: WARNING: Footnote [2] is not referenced.
pep-3115.txt:306: WARNING: Footnote [3] is not referenced.
pep-3115.txt:309: WARNING: Footnote [4] is not referenced.
pep-3119.txt:846: WARNING: Footnote [2] is not referenced.
pep-3119.txt:849: WARNING: Footnote [3] is not referenced.
pep-3119.txt:868: WARNING: Footnote [9] is not referenced.
pep-3119.txt:871: WARNING: Footnote [10] is not referenced.
pep-3135.txt:216: WARNING: Footnote [1] is not referenced.
pep-3135.txt:219: WARNING: Footnote [2] is not referenced.
pep-3100.txt:346: WARNING: Footnote [26] is not referenced.
pep-3104.txt:485: WARNING: Footnote [15] is not referenced.
pep-3114.txt:208: WARNING: Footnote [6] is not referenced.
pep-3145.txt:137: WARNING: Footnote [8] is not referenced.
pep-3147.txt:607: WARNING: Footnote [21] is not referenced.
pep-0617.rst:798: WARNING: Footnote [#] is not referenced.
pep-0622.rst:2223: WARNING: Footnote [1] is not referenced.
pep-0622.rst:2235: WARNING: Footnote [5] is not referenced.
pep-0636.rst:459: WARNING: duplicate label appendix a, other instance in pep-0634.rst
pep-0644.rst:366: WARNING: Footnote [11] is not referenced.
pep-0645.rst:151: WARNING: Footnote [2] is not referenced.
pep-0645.rst:153: WARNING: Footnote [3] is not referenced.
pep-0654.rst:1494: WARNING: Footnote [13] is not referenced.
pep-0571.rst:361: WARNING: Footnote [18] is not referenced.
pep-0572.rst:1317: WARNING: Footnote [1] is not referenced.
pep-0531.txt:634: WARNING: Footnote [4] is not referenced.
pep-0531.txt:637: WARNING: Footnote [5] is not referenced.
pep-0545.txt:573: WARNING: Footnote [2] is not referenced.
pep-0502.txt:688: WARNING: Footnote [10] is not referenced.
pep-0502.txt:692: WARNING: Footnote [11] is not referenced.
pep-0505.rst:858: WARNING: Footnote [5] is not referenced.
pep-0480.txt:888: WARNING: Footnote [6] is not referenced.
pep-0480.txt:891: WARNING: Footnote [9] is not referenced.
pep-0480.txt:892: WARNING: Footnote [10] is not referenced.
pep-0488.txt:333: WARNING: Footnote [10] is not referenced.
pep-0491.txt:537: WARNING: Footnote [1] is not referenced.
pep-0492.txt:1404: WARNING: Footnote [1] is not referenced.
pep-0448.txt:232: WARNING: Footnote [3] is not referenced.
pep-0453.txt:1024: WARNING: Footnote [1] is not referenced.
pep-0453.txt:1027: WARNING: Footnote [2] is not referenced.
pep-0453.txt:1030: WARNING: Footnote [3] is not referenced.
pep-0453.txt:1033: WARNING: Footnote [4] is not referenced.
pep-0453.txt:1036: WARNING: Footnote [5] is not referenced.
pep-0425.txt:274: WARNING: Footnote [1] is not referenced.
pep-0425.txt:277: WARNING: Footnote [2] is not referenced.
pep-0426.txt:1510: WARNING: Footnote [1] is not referenced.
pep-0400.txt:213: WARNING: duplicate label appendix a, other instance in pep-0642.rst
pep-0413.txt:916: WARNING: Footnote [2] is not referenced.
pep-0419.txt:511: WARNING: Footnote [4] is not referenced.
pep-0419.txt:514: WARNING: Footnote [5] is not referenced.
Wow, didn't know you were tracking that in such detail. That would be really good to include in the meta tracking issue I'm about to create covering that, I was just going to include a clean-up dump of the warnings I had)
The numbers may be a little off by the shifting sands of fixing other warnings (e.g. a duplicate fixed in one fixes the other), but gives a good enough idea.
If you have will and time, this would be extra helpful to hint us what is expected fix for this, where like above, the repository on bitbucket mentioned in PEP probably was removed. Web archive? Marking somehow links as not alive? Tried to find answers in https://peps.python.org/pep-0001/#pep-maintenance
it's one of the lower-priority list items given the immense number of links (many thousands) among the various PEPs, and the average age of many of them (considering the PEPs span two decades). In general, I'd only recommend doing so on PEP if you're already in the process of updating it to fix the higher-priority items in the list (warnings, wrong syntax highlighting, missing headers, substantial rendering/technical defects), and focusing on the PEPs that have the highest-priority defects and those that are Draft, Accepted and Active (for Process/Informational) or Final (for Standards Track) first over those that are Deferred, Withdrawn, Rejected or Superseded.
The job can be started by looking for any links around and assume that anything with 404 response code is broken.
You'd do this with sphinx linkcheck (or make linkcheck, which calls it), and looking for the errors (highlighted in red)
If you have will and time, this would be extra helpful to hint us what is expected fix for this
You'll want to use good case-by-case judgement, but in general, the fallback order I'd suggest is:
Try to find where the original page, or its current equivalent has been relocated to.
Use an archive.org Wayback Machine snapshot as close as possible to the date the page was originally linked (per the PEP's Git history)
If all attempts to resolve the link fail, add it to the linkcheck_ignore list in conf.py
This is much too technical and low-level for PEP 1, but I do have a draft of the meta-issue mentioned above that documents the outstanding defects considered significant enough to motivate fixes to existing PEPs, the overall strategy to address them to minimize noise, churn and notifications to authors while maximizing practical, holistic benefit, and the details of how to fix each one, but haven't quite finished it quite yet—I hope to do so very soon.
Activity
hugovk commentedon Jun 24, 2022
+1
We could also reconsider #1 "Use .rst as the file extension for reST-based PEPs", which was also rejected due to history: #1 (comment).
pradyunsg commentedon Jun 24, 2022
Indeed, that would also include #4.
CAM-Gerlach commentedon Jun 24, 2022
While it can't get us back the substantial hassle of having to finagle the includes/excludes to fix the many issues that dumping all the PEPs in the root directory and naming many of them
.txtinstead of.rsthas caused us in the past (e.g. #2423 , #2405 , #2264 , and parts of several others), it will certainly help avoid any future issues going forward, and allow us to re-simplify the custom config and plugins/hacks we have in place to deal with this. Additionally, it adds a time and complexity cost to everyday grepping as well as finding/scrolling through all the PEP files in the root to find the few important non-PEP ones. Also, its caused a fair amount of confusion in the past, since its ambiguous whether arbitrary non-PEP files in the root are meta-documentation/build scripts/config/etc. at the repo level, or are associated with individual PEPs.Given that now the main reasons for not doing this (chiefly, GitHub not tracking moves) are no longer an issue (several other things surrounding this have been improved as well), I'm 👍 on this change (moving all the PEPs to a
pepssubdir with a consistent.rstextension, and am willing to help make it happen (we'd need to tweak the makefile and build config, update the path in the linting checks, and make sure everything still works).To note, that was already completed many years ago and all the PEPs are using reST syntax internally, just that the old PEPs still used the
.txtextension (#4) for historical reasons, which are now no longer relevant as you mention.AA-Turner commentedon Jun 25, 2022
I don't remember where, but someone made the point that for PEPs, the text files are the project, rather than in support of the project, as is the case with standard documentation.
I'd be in favour of cleaning up the ancialliary files where possible, but I don't think we should move the files, even if we can.
A
hugovk commentedon Jun 25, 2022
Even so, many projects have their main project files under a subdirectory, for example
src/project_nameorproject_name, and tests and other stuff elsewhere.merwok commentedon Jun 25, 2022
That line of argument sounds a bit philosophical, but the point being discussed here is purely a practical matter due to the current code host in use.
CAM-Gerlach commentedon Jun 28, 2022
Indeed, that's pretty much all Python projects, many of which have the tests inline with the code in the subdir rather than under another subdirectory, along with many (most) other languages (e.g.
src), and even on the various docs projects I contribute to, very often the docs are still in adocssubdir, even if the top-level repo is just docs. Same with e.g. static sites, which typically include all content in acontentor similar subdir, even if there are minimal supporting files.Indeed; practicality over purity. The reasons advanced for the move are essentially all practical in nature, namely:
Therefore, if we're going to move anything anyway (which git doesn't care if its a rename or a move), we may as well just do things properly at the same time to really get the benefit of it.
Semnodime commentedon Jan 13, 2023
@CAM-Gerlach, I would like to help transition all PEPs from .txt to .rst, moving them into a common subdir, etc, by creating a PR, just as @timofurrer attempted in 2016 via timofurrer@b6afc70.
CAM-Gerlach commentedon Jan 13, 2023
The actual move (and rename of the PEPs to
.rst) is fairly trivial for any of us to do; there are a handful of other things that need to be updated/simplified afterward, but realistically that's best (and most easily) done by a PEP editor familiar with all the infrastructure involved, assuming we decide to actually go ahead with it.However, there are a number of tasks to fix outstanding technical/editorial defects that you could help with right now with relatively that should be much more achievable, helpful to use and beneficial to PEP readers and authors, such as:
To note, we don't generally suggest opening big PRs doing the same thing to a bunch of PEPs, especially as a newer contributor. Instead, a good approach to this is to pick one PEP that has at least one build warning, fix that and each of the other technical issues present (one type of fix per commit), and then submit that as a PR for review. See, e.g. #2751, #2754 or any of Hugo's other similar PRs for examples.
I plan to open a meta-issue (hopefully later today; I've already written up a lot of it) documenting this approach and tracking the main remaining defect-fixing tasks that have value and meet the criteria, with a particular eye toward making it straightforward for any contributor to help with. Keep an eye out for that if you're interested in helping out. Thanks!
hugovk commentedon Jan 14, 2023
Re: fixing warnings, here's the checklist I'd been working from.
Details
Sorted by number of warnings
Fixed warnings
Remaining warnings
CAM-Gerlach commentedon Jan 14, 2023
Wow, didn't know you were tracking that in such detail. That would be really good to include in the meta tracking issue I'm about to create covering that, I was just going to include a clean-up dump of the warnings I had)
hugovk commentedon Jan 14, 2023
The numbers may be a little off by the shifting sands of fixing other warnings (e.g. a duplicate fixed in one fixes the other), but gives a good enough idea.
rafsaf commentedon Apr 2, 2023
@CAM-Gerlach
You mentioned repairing broken external links.
The job can be started by looking for any links around and assume that anything with 404 response code is broken.
For example https://bitbucket.org/larsyencken/simplestats/src/c42e048a6625/src/basic.py in https://peps.python.org/pep-0450/
If you have will and time, this would be extra helpful to hint us what is expected fix for this, where like above, the repository on bitbucket mentioned in PEP probably was removed. Web archive? Marking somehow links as not alive? Tried to find answers in https://peps.python.org/pep-0001/#pep-maintenance
CAM-Gerlach commentedon Apr 2, 2023
it's one of the lower-priority list items given the immense number of links (many thousands) among the various PEPs, and the average age of many of them (considering the PEPs span two decades). In general, I'd only recommend doing so on PEP if you're already in the process of updating it to fix the higher-priority items in the list (warnings, wrong syntax highlighting, missing headers, substantial rendering/technical defects), and focusing on the PEPs that have the highest-priority defects and those that are Draft, Accepted and Active (for Process/Informational) or Final (for Standards Track) first over those that are Deferred, Withdrawn, Rejected or Superseded.
You'd do this with
sphinx linkcheck(ormake linkcheck, which calls it), and looking for the errors (highlighted in red)You'll want to use good case-by-case judgement, but in general, the fallback order I'd suggest is:
linkcheck_ignorelist inconf.pyIn this case, I just googled
larsyencken simplestatsand the first hit was the GitHub repo corresponding to that project. I can't be 100% sure which exact commit was linked, the hash in the URL presumably corresponds to a Mercurial changeset rather than a Git commit, but given per the URL it was before the package directory was changed fromsrctosimplestats, and there was only one change to the file since the initial version prior to thesrcchange, which was on the same day as the other change, the link should thus be updated to point to https://github.com/larsyencken/simplestats/blob/2be84e46814786b0cf2e88671bdb02aa7d39ef6b/src/basic.pyThis is much too technical and low-level for PEP 1, but I do have a draft of the meta-issue mentioned above that documents the outstanding defects considered significant enough to motivate fixes to existing PEPs, the overall strategy to address them to minimize noise, churn and notifications to authors while maximizing practical, holistic benefit, and the details of how to fix each one, but haven't quite finished it quite yet—I hope to do so very soon.
AA-Turner commentedon Sep 9, 2023
This marks the closure of the final 'early' issue in the PEPs repo -- thanks to everyone for helping here!
A