Use :cpy-file: throughout the Devguide
#984
Conversation
| Developers can choose to follow labels, so if a label that they are | ||
| following is added to an issue or pull request, they will be notified | ||
| automatically. The :file:`CODEOWNERS` file is also used to indicate | ||
| automatically. The :cpy-file:`.github/CODEOWNERS` file is also used to indicate |
There was a problem hiding this comment.
If we add ~ support to :cpy-file: we could hide the dir.
| Functions named ``test_*`` are used as tests directly. | ||
| Tests that need Python code (or are just easier to partially write in Python) | ||
| live in ``Lib/test``, mainly in :file:`Lib/test/test_capi.py`. | ||
| live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`. |
There was a problem hiding this comment.
test_capi is now a dir.
| very beginning of the compiler or the end, you need to care about how the arena | ||
| works. All code relating to the arena is in either | ||
| :file:`Include/Internal/pycore_pyarena.h` or :file:`Python/pyarena.c`. | ||
| :cpy-file:`Include/internal/pycore_pyarena.h` or :cpy-file:`Python/pyarena.c`. |
There was a problem hiding this comment.
internal is lowercase. There were a few similar errors in this file.
| Parser for ASDL definition files. Reads in an ASDL description | ||
| and parses it into an AST that describes it. | ||
|
|
||
| asdl_c.py |
There was a problem hiding this comment.
All the files in this section should be linkified. I left a comment about it in the PR.
| Functions named ``test_*`` are used as tests directly. | ||
| Tests that need Python code (or are just easier to partially write in Python) | ||
| live in ``Lib/test``, mainly in :file:`Lib/test/test_capi.py`. | ||
| live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`. |
There was a problem hiding this comment.
We could also link things that aren't already :file:, like Lib/test:
| live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`. | |
| live in :cpy-file:`Lib/test`, mainly in :cpy-file:`Lib/test/test_capi`. |
There's a lot more that could be linked on this page too, especially the first few sections.
But let's keep the scope of this PR to replacing the old :file: with the new :cpy-file:.
There was a problem hiding this comment.
Agreed on keeping the PR focused. We should also try to create links only when/where they are useful, but there are definitely more places where :cpy-file: can be used.
3 participants
This PR replaces the use of
:file:with:cpy-file:(introduced in #961) in most places. Since the generated links are now checked bymake linkcheck, I also went through and corrected some of those.There are a few broken links that I haven't touched yet:
Include/Python-ast.hwas removed by @vstinnerInclude/token.hwas removed by @vstinnerInclude/code.hwas removed by @vstinnerPython/peephole.cwas removed by @markshannonThe respective sections in
developer-workflow/grammar.rstandinternals/compiler.rstmight need to be revisited.@vstinner and @markshannon: can you advise on whether these are quick fixes that we can include in this PR or if they should be handled separately?
I also found another issue with this section: https://devguide.python.org/internals/compiler/#important-files
In addition to the fact that the listed files don't use any markup, the markup used for most of the files seem incorrect (it's a blockquote due to the indentation). A nested list with full paths for all the files and
:cpy-file:should be a better alternative.The
:cpy-file:role could also be improved to support~, so that in that list (and in a few other places) we can hide the full path and just display the file name.