Description
- Reword each section of the syntax chapters of the
Python Language Reference:
- Lexical analysis
- Expressions
- Simple statements
- Compound statements
- Top-level components
- Synchronize the documented formal grammar with Python’s actual grammar. (Both will need changing.)
- Automatically generate as much of the formal grammar snippets as possible.
- Add railroad diagrams to the docs.
- Move the non-syntax chapters (Data model, Execution model, The import system) out of the Language Reference, and possibly rename it to Python Syntax Reference.
Benefits
Better syntax docs that match current Python.
Decisions
- Is this a good direction?
- Is the style good? See the mostly finished Lexical analysis chapter and the current work on Expressions.
Challenges and risks
- There is an abrupt change in style between the rewritten chapters and the rest that is still untouched.
- The work is moving slowly, and depends on one person.
How to help
The lead is not looking for people to take this on, since reviewing would be as hard as writing. Feedback on the direction and style is welcome. The work happens on weekly livestreams: see the Python Docs Discord.