sphinx_source_tree module

sphinx-source-tree

Generate a reStructuredText file containing an ASCII project tree and literalinclude directives for every source file.

Reads defaults from [tool.sphinx-source-tree] in pyproject.toml. Per-file settings live under [[tool.sphinx-source-tree.files]]. CLI arguments always take precedence.

sphinx_source_tree.build_parser() → ArgumentParser

Create the argument parser (exposed for documentation / testing).

sphinx_source_tree.build_tree(path: Path, *, max_depth: int, ignore: list[str], whitelist: list[str], include_all: bool, root: Path, prefix: str = '') → str

Return an ASCII directory tree for path (recursive).

Entries are filtered before connectors are assigned so that the last visible entry always receives └──.

sphinx_source_tree.collect_files(root: Path, *, extensions: list[str], ignore: list[str], whitelist: list[str], include_all: bool) → list[Path]

Return a sorted list of files eligible for literalinclude.

sphinx_source_tree.detect_language(path: Path, extra: dict[str, str] | None = None) → str

Map a file suffix to its Sphinx highlight language string.

sphinx_source_tree.generate(project_root: Path | str = '.', output: Path | str = 'docs/source_tree.rst', *, depth: int = 10, extensions: list[str] | None = None, ignore: list[str] | None = None, whitelist: list[str] | None = None, include_all: bool = True, title: str = 'Project source-tree', linenos: bool = False, extra_languages: dict[str, str] | None = None, file_options: dict[str, dict[str, Any]] | None = None, order: list[str] | None = None) → str

Build the full .rst document and return it as a string.

Parameters

project_root:

Path to the project directory.

output:

Destination .rst path (used to compute relative literalinclude paths, not written by this function).

depth:

Maximum tree depth.

extensions:

File suffixes to include via literalinclude.

ignore:

Glob patterns to skip (matched against both relative path and file name).

whitelist:

Directories to restrict to (ignored when include_all is true).

include_all:

Bypass the whitelist.

title:

RST section title.

linenos:

Add :linenos: to every literalinclude.

extra_languages:

Additional {suffix: language} mappings merged on top of the built-in LANGUAGE_MAP.

file_options:

Per-file literalinclude inclusion-range options. Keys are file paths relative to project_root (or absolute); values are dicts with any subset of: lines, start-at, start-after, end-before, end-at. Example:

{
    "src/app.py": {"end-before": "# ===== Tests ====="},
    "src/utils.py": {"lines": "1-40"},
}

In pyproject.toml (top-level, or as the default profile):

[tool.sphinx-source-tree.file-options]
"src/app.py" = {"end-before" = "# ===== Tests ====="}
"src/utils.py" = {"lines" = "1-40"}

Named profiles are defined under [tool.sphinx-source-tree.file-options-profiles.<name>] and selected per output file via file-options-profile. When called directly the file_options argument already contains the resolved (profile-selected) mapping; profile resolution happens in _generate_from_cfg.

order:

Explicit ordering for the literalinclude listing. Each element is a file path relative to project_root (absolute paths are also accepted). Files listed here appear first, in the given sequence; all remaining collected files follow in their default sorted order. Files not present in the collected set (e.g. excluded by extension or ignore rules) are silently skipped with a stderr warning.

This option does not affect the ASCII directory tree — only the literalinclude blocks.

Example in pyproject.toml:

[tool.sphinx-source-tree]
order = [
    "README.rst",
    "pyproject.toml",
    "src/app.py",
]

Or per [[files]] entry:

[[tool.sphinx-source-tree.files]]
output = "docs/source_tree.rst"
order = ["src/core.py", "src/utils.py"]

sphinx_source_tree.load_config(project_root: Path) → dict[str, Any]

Load [tool.sphinx-source-tree] from pyproject.toml.

Returns the full section dict, which may contain a files key (list of per-file override dicts) alongside top-level defaults.

sphinx_source_tree.main(argv: list[str] | None = None) → None

Entry point for the sphinx-source-tree command.

sphinx_source_tree.resolve_config(cli_ns: Namespace, defaults: dict[str, Any] | None = None) → dict[str, Any]

Merge defaults < pyproject.toml < CLI arguments.

Only CLI values that were explicitly provided (not None) override.

When [[tool.sphinx-source-tree.files]] entries are present the returned dict contains a "files" key: a list of fully-resolved per-file configs (each already merged with top-level pyproject defaults and CLI overrides).

View llms.txt version