This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: The grammar misses links that are present everywhere else
Type: enhancement Stage: test needed
Components: Documentation Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Arthur-Milchior, docs@python, lukasz.langa, pablogsal
Priority: normal Keywords:

Created on 2021-10-25 02:25 by Arthur-Milchior, last changed 2022-04-11 14:59 by admin.

Messages (1)
msg404946 - (view) Author: Arthur Milchior (Arthur-Milchior) * Date: 2021-10-25 02:25
The grammar, in https://docs.python.org/3/reference/grammar.html , lacks some utilities that the remaining of the documentation have.
While it remains usable, it is hard to navigate. As an example https://www.python.org/dev/peps/pep-0634/ 's "star_named_exrpsession" and "block" links to the general grammar page, and indeed can't link to the specific rules as there are no anchor on them.
This would also allow a related improvement: being able to click on a rule R in the right side of a declaration and go to the definition of R. Given the recursive nature of grammar, that would transform a sequence of search into a sequence of click (and even allow to use the browser's "back" to go back to the previous definition, or to open the new definition in a new tab)

As far as I can tell, the first action would be to add a new kind of token on Doc/tools/extensions/peg_highlight.py , so that we distinguish the left and the right part of the rule. The left part (the name of the declared rule) would be easy to recognize as it always start on the beginning of the line and end with :.
The second action would be that, for each declaration D, the html would contain an anchor "#D". And each time D would appear on the right hand side of a rule, it would be in a link to #D

I suspect that adding those links and anchor could be done by overriding the default formatter or highlighter, but I don't understand pygment well enough to know what should be done here
History
Date User Action Args
2022-04-11 14:59:51adminsetgithub: 89765
2021-11-02 03:23:50terry.reedysetnosy: + lukasz.langa, pablogsal
stage: test needed

versions: - Python 3.6, Python 3.7, Python 3.8, Python 3.9, Python 3.10
2021-10-25 02:25:53Arthur-Milchiorcreate