from __future__ import annotations
import types
import typing
from pathlib import Path
if typing.TYPE_CHECKING:
from sphinx.application import Sphinx
from . import __version__
from .core import feed_sphinx_apidoc, rename_files, sanitize_path
def _execute(
package_dir: Path,
doc_dir: Path,
package_name: Path | None,
suffix: str,
excluded_files: typing.Iterable[str],
module_first: bool,
implicit_namespaces: bool,
) -> None:
extra_args = []
if module_first:
extra_args.append("--module-first")
feed_sphinx_apidoc(
str(doc_dir),
str(package_dir),
"--full", # without `full` sphinx-build cannot find `index.rst`
*extra_args,
suffix=suffix,
implicit_namespaces=implicit_namespaces,
)
rename_files(
doc_dir,
package_dir,
(sanitize_path(package_name) if package_name is not None else None),
suffix,
implicit_namespaces=implicit_namespaces,
excluded_files=excluded_files,
)
def _builder_inited(app: Sphinx) -> None:
config = app.config
docdir = app.srcdir
package_dir: str = config.sphinx_nested_apidoc_package_dir
package_name: str = config.sphinx_nested_apidoc_package_name
suffix: str = config.sphinx_nested_apidoc_suffix
excluded_files: list[str] = config.sphinx_nested_apidoc_excluded_files
module_first: bool = config.sphinx_nested_apidoc_module_first
implicit_namespaces: bool = config.sphinx_nested_apidoc_implicit_namespaces
_execute(
Path(package_dir),
Path(docdir),
Path(package_name),
suffix,
excluded_files,
module_first,
implicit_namespaces,
)
[docs]
def setup(app: Sphinx) -> dict[str, str | bool]:
app.connect("builder-inited", _builder_inited)
# package_dir is where our package to document resides.
app.add_config_value(
"sphinx_nested_apidoc_package_dir",
None,
"env",
[str],
)
# Name of the directory to put the package documentation in. By
# default it is the name of the package itself.
app.add_config_value(
"sphinx_nested_apidoc_package_name",
None,
"env",
[str, types.NoneType],
)
# The suffix of the generated documentation files.
app.add_config_value(
"sphinx_nested_apidoc_suffix",
"rst",
"env",
[str],
)
# List of files to exclude from modification/renaming.
app.add_config_value(
"sphinx_nested_apidoc_excluded_files",
("index", "modules"),
"env",
[list],
)
# put module documentation before submodule documentation.
app.add_config_value(
"sphinx_nested_apidoc_module_first",
False,
"env",
[bool],
)
# interpret module paths according to PEP-0420 implicit namespaces
# specification.
app.add_config_value(
"sphinx_nested_apidoc_implicit_namespaces",
False,
"env",
[bool],
)
return {"version": __version__, "parallel_read_safe": True}