`papyri.toc:_tree`

source: /papyri/toc.py :25

Signature

   def     _tree (    current_path  :  str    ,    unnest  :  dict[str, list[str]]    ,    counter  :  dict[str, int]    ,    depth  :  int    =  0     )   →  dict[str, Any]

Summary

Recursively build a nested toctree dict rooted at current_path.

Extended Summary

Walks the flat toctree adjacency map unnest (node -> list of child references as written in the source) and returns a nested {child_path: {grandchild_path: {...}}} dict describing the tree reachable from current_path.

Path model:

Nodes are addressed with :-separated keys (e.g. pkg:sub:page); the last segment is the page name and the prefix is its "directory". Child references in unnest are written in source form using / and may be relative (../sibling, sub/page). For each child reference this function:

drops empty entries,
skips absolute (/...) and external (https://) refs,
rewrites a trailing / to /index (Sphinx directory-index convention),
resolves .. segments against current_path's directory via dotdotcount,
strips a trailing .rst,
then recurses.

Side effects / bookkeeping:

counter maps every known node to a visit count. It is incremented for current_path on entry, so callers can detect nodes referenced 0 times (orphans) or >1 times (multi-parent). A reference whose resolved path is not in counter is treated as dangling and skipped with a printed warning.
Asserts that the resolved child path is neither current_path itself nor already present among siblings — i.e. the input must describe a tree, not a DAG with duplicate edges.

depth is informational only (used by the commented-out debug prints); it does not affect the result.

Aliases

papyri.toc._tree