sphinx-toctree-print

#!/usr/bin/env python3
"""
Prints the global toctree hierarchy generated as part of a Sphinx build.

Requires that :file:`build/doctrees/environment.pickle` exists.
"""
import pickle
import sphinx.addnodes
from pathlib import Path
from sys import argv

DOCTREES = Path("build/doctrees/")


def main():
    with open(DOCTREES / "environment.pickle", "rb") as f:
        env = pickle.load(f)

    print_toctree(env.config.master_doc)


def print_toctree(ref, title = None, level = 0):
    indent = "  "

    if "://" in ref:
        # ref is a URI
        print(indent * level + f"{title} <{ref}>")
    elif ref == "self":
        pass
    else:
        # ref is a local doc name
        print(indent * level + ref)

        toctrees = load_toctree_nodes(ref)

        for toctree in toctrees:
            if toctree["caption"]:
                print(indent * (level + 1) + f"[{toctree['caption']}]")
                next_level = level + 2
            else:
                next_level = level + 1

            for title, subref in toctree["entries"]:
                print_toctree(subref, title = title, level = next_level)


def load_toctree_nodes(docname):
    with open(DOCTREES / f"{docname}.doctree", "rb") as f:
        doc = pickle.load(f)

    return list(doc.traverse(sphinx.addnodes.toctree))


if __name__ == "__main__":
    try:
        DOCTREES = Path(argv[1])
    except IndexError:
        pass
    main()