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) -> 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".

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).