Reformat "Important Files" section in compiler.rst

internals/compiler.rst

@@ -524,140 +524,112 @@ statement in ``_PyEval_EvalFrameDefault()``.
 Important Files
 ===============
 
-+ Parser/
+* :cpy-file:`Parser/`
+ * :cpy-file:`Parser/Python.asdl`: ASDL syntax file.
 
- Python.asdl
- ASDL syntax file
+* :cpy-file:`Parser/asdl.py`: Parser for ASDL definition files.
+Reads in an ASDL description and parses it into an AST that describes it.
 
- asdl.py
- Parser for ASDL definition files. Reads in an ASDL description
- and parses it into an AST that describes it.
+* :cpy-file:`Parser/asdl_c.py`: Generate C code from an ASDL description.
+Generates :cpy-file:`Python/Python-ast.c` and
+:cpy-file:`Include/internal/pycore_ast.h`.
 
- asdl_c.py
- "Generate C code from an ASDL description." Generates
- :cpy-file:`Python/Python-ast.c` and :cpy-file:`Include/internal/pycore_ast.h`.
+ * :cpy-file:`Parser/parser.c`: The new PEG parser introduced in Python 3.9.
+ Generated by :cpy-file:`Tools/peg_generator/pegen/c_generator.py`
+ from the grammar :cpy-file:`Grammar/python.gram`. Creates the AST from
+ source code. Rule functions for their corresponding production rules
+ are found here.
 
- parser.c
- The new PEG parser introduced in Python 3.9.
- Generated by :cpy-file:`Tools/peg_generator/pegen/c_generator.py`
- from the grammar :cpy-file:`Grammar/python.gram`. Creates the AST from
- source code. Rule functions for their corresponding production rules
- are found here.
+ * :cpy-file:`Parser/peg_api.c`: Contains high-level functions which are
+ used by the interpreter to create an AST from source code.
 
- peg_api.c
- Contains high-level functions which are used by the interpreter to
- create an AST from source code .
+ * :cpy-file:`Parser/pegen.c`: Contains helper functions which are used
+ by functions in :cpy-file:`Parser/parser.c` to construct the AST.
+ Also contains helper functions which help raise better error messages
+ when parsing source code.
 
- pegen.c
- Contains helper functions which are used by functions in
- :cpy-file:`Parser/parser.c` to construct the AST. Also contains helper
- functions which help raise better error messages when parsing source
- code.
+ * :cpy-file:`Parser/pegen.h`: Header file for the corresponding
+ :cpy-file:`Parser/pegen.c`. Also contains definitions of the ``Parser``
+ and ``Token`` structs.
 
- pegen.h
- Header file for the corresponding :cpy-file:`Parser/pegen.c`. Also contains
- definitions of the ``Parser`` and ``Token`` structs.
+* :cpy-file:`Python/`
+ * :cpy-file:`Python/Python-ast.c`: Creates C structs corresponding to
+ the ASDL types. Also contains code for marshalling AST nodes (core
+ ASDL types have marshalling code in :cpy-file:`Python/asdl.c`).
+ "File automatically generated by :cpy-file:`Parser/asdl_c.py`".
+ This file must be committed separately after every grammar change
+ is committed since the ``__version__`` value is set to the latest
+ grammar change revision number.
 
-+ Python/
+ * :cpy-file:`Python/asdl.c`: Contains code to handle the ASDL sequence type.
+ Also has code to handle marshalling the core ASDL types, such as number
+ and identifier. Used by :cpy-file:`Python/Python-ast.c` for marshalling
+ AST nodes.
 
- Python-ast.c
- Creates C structs corresponding to the ASDL types. Also
- contains code for marshalling AST nodes (core ASDL types have
- marshalling code in :cpy-file:`Python/asdl.c`). "File automatically
- generated by :cpy-file:`Parser/asdl_c.py`". This file must be
- committed separately after every grammar change is committed since
- the ``__version__`` value is set to the latest grammar change
- revision number.
+ * :cpy-file:`Python/ast.c`: Used for validating the AST.
 
- asdl.c
- Contains code to handle the ASDL sequence type. Also has code
- to handle marshalling the core ASDL types, such as number and
- identifier. Used by :cpy-file:`Python/Python-ast.c` for marshalling
- AST nodes.
+ * :cpy-file:`Python/ast_opt.c`: Optimizes the AST.
 
- ast.c
- Used for validating the AST.
+* :cpy-file:`Python/ast_unparse.c`: Converts the AST expression node
+back into a string (for string annotations).
 
- ast_opt.c
- Optimizes the AST.
+ * :cpy-file:`Python/ceval.c`: Executes byte code (aka, eval loop).
 
- ast_unparse.c
- Converts the AST expression node back into a string
- (for string annotations).
+ * :cpy-file:`Python/compile.c`: Emits bytecode based on the AST.
 
- ceval.c
- Executes byte code (aka, eval loop).
+ * :cpy-file:`Python/symtable.c`: Generates a symbol table from AST.
 
- compile.c
- Emits bytecode based on the AST.
+ * :cpy-file:`Python/peephole.c`: Optimizes the bytecode.
 
- symtable.c
- Generates a symbol table from AST.
+ * :cpy-file:`Python/pyarena.c`: Implementation of the arena memory manager.
 
- peephole.c
- Optimizes the bytecode.
+ * :cpy-file:`Python/wordcode_helpers.h`: Helpers for generating bytecode.
 
- pyarena.c
- Implementation of the arena memory manager.
+* :cpy-file:`Python/opcode_targets.h`: One of the files that must be
+modified if :cpy-file:`Lib/opcode.py` is.
 
- wordcode_helpers.h
- Helpers for generating bytecode.
+* :cpy-file:`Include/`
+ * :cpy-file:`Include/code.h`: Header file for :cpy-file:`Objects/codeobject.c`;
+ contains definition of ``PyCodeObject``.
 
- opcode_targets.h
- One of the files that must be modified if :cpy-file:`Lib/opcode.py` is.
+* :cpy-file:`Include/opcode.h`: One of the files that must be modified if
+ :cpy-file:`Lib/opcode.py` is.
 
-+ Include/
+ * :cpy-file:`Include/internal/pycore_ast.h`: Contains the actual definitions
+ of the C structs as generated by :cpy-file:`Python/Python-ast.c`.
+ "Automatically generated by :cpy-file:`Parser/asdl_c.py`".
 
- code.h
- Header file for :cpy-file:`Objects/codeobject.c`; contains definition of
- ``PyCodeObject``.
+ * :cpy-file:`Include/internal/pycore_asdl.h`: Header for the corresponding
+ :cpy-file:`Python/ast.c`.
 
- opcode.h
- One of the files that must be modified if :cpy-file:`Lib/opcode.py` is.
+* :cpy-file:`Include/internal/pycore_ast.h`: Declares ``_PyAST_Validate()``
+external (from :cpy-file:`Python/ast.c`).
 
- + internal/
+ * :cpy-file:`Include/internal/pycore_symtable.h`: Header for
+ :cpy-file:`Python/symtable.c`. ``struct symtable`` and ``PySTEntryObject``
+ are defined here.
 
- pycore_ast.h
- Contains the actual definitions of the C structs as generated by
- :cpy-file:`Python/Python-ast.c`.
- "Automatically generated by :cpy-file:`Parser/asdl_c.py`".
+ * :cpy-file:`Include/internal/pycore_parser.h`: Header for the
+ corresponding :cpy-file:`Parser/peg_api.c`.
 
- pycore_asdl.h
- Header for the corresponding :cpy-file:`Python/ast.c`
+* :cpy-file:`Include/internal/pycore_pyarena.h`: Header file for the
+ corresponding :cpy-file:`Python/pyarena.c`.
 
- pycore_ast.h
- Declares ``_PyAST_Validate()`` external (from :cpy-file:`Python/ast.c`).
+* :cpy-file:`Objects/`
+ * :cpy-file:`Objects/codeobject.c`: Contains PyCodeObject-related code
+ (originally in :cpy-file:`Python/compile.c`).
 
- pycore_symtable.h
- Header for :cpy-file:`Python/symtable.c`. ``struct symtable`` and
- ``PySTEntryObject`` are defined here.
+* :cpy-file:`Objects/frameobject.c`: Contains the ``frame_setlineno()``
+function which should determine whether it is allowed to make a jump
+between two points in a bytecode.
 
- pycore_parser.h
- Header for the corresponding :cpy-file:`Parser/peg_api.c`.
+* :cpy-file:`Lib/`
+ * :cpy-file:`Lib/opcode.py`: Master list of bytecode; if this file is
+ modified you must modify several other files accordingly
+ (see "`Introducing New Bytecode`_")
 
- pycore_pyarena.h
- Header file for the corresponding :cpy-file:`Python/pyarena.c`.
-
-
-+ Objects/
-
- codeobject.c
- Contains PyCodeObject-related code (originally in
- :cpy-file:`Python/compile.c`).
-
- frameobject.c
- Contains the ``frame_setlineno()`` function which should determine
- whether it is allowed to make a jump between two points in a bytecode.
-
-+ Lib/
-
- opcode.py
- Master list of bytecode; if this file is modified you must modify
- several other files accordingly (see "`Introducing New Bytecode`_")
-
- importlib/_bootstrap_external.py
- Home of the magic number (named ``MAGIC_NUMBER``) for bytecode
- versioning.
+ * :cpy-file:`Lib/importlib/_bootstrap_external.py`: Home of the magic number
+ (named ``MAGIC_NUMBER``) for bytecode versioning.
 
 
 Known Compiler-related Experiments