Module doctree 

Typed doctree IR with docutils-equivalent node semantics (M2 wave 1).

Design (recorded in docs/superpowers/plans/2026-08-07-m2-wave-map.md): docutils-mirror generic node — node identity and attributes are data, not Rust types, so the pseudo-XML parity serializer is a direct dump and docutils transforms/writers port line-by-line. One Node struct covers every element type; kind holds the docutils tagname from kinds.

Source spans are structural: every node carries a Span with real (source, line) provenance plus the byte range of its text in the parser’s processed source (docutils itself only keeps (source, line)). Spans are line-granular; the inline parser stamps its nodes with the enclosing text block’s span.

Modules

ids

docutils-exact id/name normalization and the document id registry.

kinds

docutils element tagnames.

messages

system_message node construction with docutils-exact shape.

pformat

Pseudo-XML emitter, byte-identical to docutils document.pformat().

Structs

Attrs

docutils’ universal list attributes (basic_attributes + backrefs) as typed fields, plus an open, name-sorted list for everything else (refuri, enumtype, level, …). pformat merges both sets and prints all pairs in one alphabetical sequence, exactly like docutils attlist().

Doctree

One parsed document. root.kind == kinds::DOCUMENT.

Node

One doctree node. Element nodes have text == None; text leaves have kind == kinds::TEXT, Some(text), and no children or attributes.

Span

Source provenance of a node: which source it came from, the 1-based line docutils would report for it, and the byte range of its text.

Enums

AttrValue

Attribute value. docutils attribute dicts hold ints and strings for everything wave 1 emits; docutils’ five universal list attributes (ids, names, …) live in Attrs’ typed fields instead.

Functions

from_bincode

Decode a doctree previously written by to_bincode. Also the entry point for bytes that weren’t — a corrupted file, or a stale/foreign blob from a version-skewed cache — which can fail for the usual decode reasons and additionally once decoding would intern more than intern’s bounded table allows (see src/doctree/intern.rs).

to_bincode

Encode a doctree to its bincode wire format (config: standard()). Infallible in practice: every field either derives Serialize or goes through the interner’s plain string encoding, neither of which can fail.