Module rst 

Recursive-descent RST parser with docutils-0.22.4 fidelity (M2 wave 1: block grammar only — the inline parser arrives in wave 2).

Fidelity contract: output pformat() is byte-identical to docutils.parsers.rst.Parser parse-layer output for the construct set in tests/fixtures/doctree_differential.json. Transforms (doctitle promotion, target propagation, transition hoisting, message filtering) are explicitly NOT applied here; they arrive as separate components in later waves. Behavior sources: the committed differential fixture and the probe notes in docs/superpowers/plans/2026-08-07-m2-wave1-probes.md.

Modules

inline

The inline parser (M2 wave 2): a port of docutils states.py Inliner for emphasis/strong/literal recognition, escape semantics, and the problematic/unclosed machinery. References, roles, and footnote references extend this module in later wave-2 tasks.

lines

Line preprocessing: docutils statemachine.string2lines(tab_width=8, convert_whitespace=True) equivalent, producing the parser’s line stream as index-based LineRec records over a processed source text.

Structs

DirectiveRecord

Pre-conversion directive tuple mirroring the M1 validation scanner’s semantics (whitespace-split args, inline-admonition content routing, raw string options) — the feed for DirectiveValidationSystem.

ObjectRegistration

One StandardDomain.note_object call the parse layer made (GenericObject/ConfigurationValue.add_target_and_index).

ParseLogWarning

One logger.warning a directive raised during the parse.

ParseOptions

ParseOutput

Everything a parse produces: the doctree plus the flat records the build pipeline consumes without re-walking raw source.

ProgramOptionRecord

One Cmdoption.add_target_and_index call the parse layer made (sphinx/domains/std/__init__.py:308-315).

PyModuleRecord

One PythonDomain.note_module call (PyModule.run, domains/python/__init__.py:515-521) — the modname → ModuleEntry registration feeding the env layer and, later, the py-modindex.

PyObjectRecord

One PythonDomain.note_object call the parse layer made (PyObject.add_target_and_index, domains/python/_object.py:415-437, or PyModule.run, __init__.py:522) — the fullname → ObjectEntry registration the env layer replays, plus the provenance the duplicate-description warning needs.

RegistryExport

What the parse layer hands the environment besides the doctree itself: state that lives in the parser (the docutils id/name registry, Sphinx’s env.ref_context) and dies with it, but that env collectors need.

RoleRecord

A role occurrence (sphinx mode): validation + nitpicky feed.

ToctreeEntryRecord

ToctreeRecord

A toctree directive occurrence (sphinx mode).

Constants

DEFAULT_SOURCE_ENCODING

Sphinx’s default source_encoding (config.py:244).

Functions

parse_rst

Parse RST source into a doctree. Total: never panics, never errors — problems become system_message nodes, exactly like docutils.

parse_rst_full