Module toctree 

Sphinx’s toctree bookkeeping: the read-phase half of sphinx/environment/collectors/toctree.py plus the two pieces of sphinx/directives/other.py and sphinx/environment/adapters/toctree.py that feed it.

Three ports live here, in the order the build runs them:

1. resolve_entries — TocTree.parse_content (directives/other.py:88): turns the directive’s raw content lines into the entries/includefiles attributes of the toctree node, resolving relative docnames, expanding :glob: patterns and dropping targets that aren’t real documents. This is environment-dependent (it needs the full docname set), which is why the parser takes a found_docs set: Sphinx resolves at parse time too, from env.found_docs.

2. build_toc — TocTreeCollector.process_doc (collectors/toctree.py:64): the document’s local table of contents as a doctree-shaped bullet_list, with every toctree node copied into it.

3. note_toctree — adapters/toctree.py:32: the toctree graph (toctree_includes, files_to_rebuild, glob_toctrees, numbered_toctrees).

4. collect_relations / toctree_ancestors / check_consistency — the whole-project reads of that graph (environment/__init__.py:778-823, adapters/toctree.py:562), which only make sense once every document has been noted.

5. resolve_toctree — _resolve_toctree (adapters/toctree.py:119): the write-phase expansion of a toctree node into nested bullet lists, as far as the search index needs it (see its doc comment for what the HTML writer will still have to add).

document_title is the neighbouring TitleCollector.process_doc (collectors/title.py:27), which shares this module’s SphinxContentsFilter port.

NOT here (later wave-4 tasks): assign_section_numbers / assign_figure_numbers (they write toc_secnumbers/toc_fignumbers and stamp secnumber onto the references this module builds).

Structs

ConsistencyMessage

One diagnostic from check_consistency, located at a document rather than at a source line (Sphinx passes location=docname).

ResolvedEntries

toctree['entries'] (title, ref) pairs plus toctree['includefiles'].

ToctreeContent

Everything one toctree directive needs resolved against the project’s document set — the inputs of TocTree.parse_content.

ToctreeWarning

One diagnostic produced while resolving a toctree’s entries.

Enums

ConsistencyLevel

Whether a ConsistencyMessage is a warning (counts toward -W) or an informational note.

ToctreeWarningKind

What kind of toctree diagnostic this is, kept alongside the Sphinx message so the builder can map it onto its own coarse crate::error::WarningType.

Functions

build_toc

The document’s local table of contents (env.tocs[docname]) and its entry count (env.toc_num_entries[docname]).

check_consistency

Post-read consistency checks over the finished toctree graph.

collect_relations

Every document’s [parent, prev, next], from a pre-order walk of the toctree graph rooted at env.root_doc.

docname_join

Sphinx docname_join (util/__init__.py): posixpath.normpath(posixpath.join('/' + basedocname, '..', docname))[1:] — a leading / makes the target source-root-relative, anything else is relative to the referencing document’s directory, and ./.. segments are normalized.

document_title

env.titles[docname]: a fresh title node holding the first section title’s contents, filtered exactly like a toc entry’s.

note_toctree

Record one toctree node’s file relations in the environment.

resolve_entries

Resolve a toctree directive’s content lines against the document set.

resolve_toctree

Resolve a toctree node into the nested bullet lists Sphinx writes in its place: _resolve_toctree (adapters/toctree.py:119-220) with the arguments the write phase passes for a document’s own toctrees (get_and_resolve_doctree: prune=True, the node’s own maxdepth, collapse=False, includehidden=False).

split_explicit_title

Split Some Title <target> into its two halves, as Sphinx’s explicit_title_re (^(.+?)\s*<(.*?)>$, util/nodes.py) does: the first < that leaves a non-empty title wins, and the line must end with >. A bare <foo> is therefore a literal target named <foo>, not an empty-titled reference.

toctree_ancestors

The chain of toctree parents above docname, nearest first, starting with docname itself.

toctree_copies

Every toctree node inside a built toc, in the order build_toc copied them in — which is the order Sphinx calls note_toctree in, since it notes each node at the moment it copies it.

traverse_toctree

Pre-order depth-first walk of toctree_includes from root, yielding (parent, docname) once per document — the first visit wins.

Type Aliases

Relation

[parent, prev, next] — one document’s place in the global document order, as env.collect_relations() records it.