sphinx_nested_apidoc.core module

sphinx_nested_apidoc.core.sanitize_path(path_: Path) → Path[source]

Eliminates double slashes and relative path nastiness from the given path by treating them as relative to root path.

Parameters:

path – A string representing the path to be sanitized.

Returns:

Sanitized path as string.

Note

On Windows, if the path contains a different drive letter, it will return an empty string.

sphinx_nested_apidoc.core.feed_sphinx_apidoc(output_dir: str, module_path: str, *sphinx_arguments: str, implicit_namespaces: bool = False, force: bool = False, suffix: str = 'rst') → bool[source]

Pass commands and flags to sphinx-apidoc.

Parameters:

  • output_dir – Directory where sphinx-apidoc should store its generated files.

  • module_path – The path to the package that is being documented. Note that it is more appropriate to call it package_path but we are following sphinx-apidoc’s conventions here.

  • sphinx_arguments – The flags and command to pass to sphinx-apidoc.

Keyword Arguments:

  • implicit_namespaces – Interpret module paths according to PEP-0420 implicit namespaces specification.

  • force – Replace existing files.

  • suffix – File suffix of the generated files.

Returns:

True if help flag is passed, otherwise False.

Caution

sphinx-apidoc cannot handle situations where the supposed file in the output_dir is actually a directory.

sphinx_nested_apidoc.core.yield_source_files(source_dir: Path, extension: str = 'rst') → Iterator[Path][source]

Yields files from source directory that end with the given extension.

Parameters:

  • source_dir – The directory where the files are located.

  • extension – The extension of the file, without the “.” prefix.

Yields:

Path to file that end with extension.

Raises:

ValueError – If extension starts with a “.”.

sphinx_nested_apidoc.core.get_nested_dir_filename(sphinx_source_file: Path) → Path[source]

Convert a sphinx-apidoc based source file name into a nested directory based path.

Parameters:

sphinx_source_file – A sphinx-apidoc generated file.

Returns:

A string representing the path of the file.

Note

It does not handle the case where the source file is actually an index for a module, i.e. It does not rename “a.b.module.rst” to “some/path/a/b/module/index.rst”. Use get_destination_filename() for that.

sphinx_nested_apidoc.core.is_packagedir(directory: Path) → bool[source]

Checks if given directory is a package.

This function caches its input to improve performance.

sphinx_nested_apidoc.core.get_destination_filename(sphinx_source_file: Path, package_dir: Path, extension: str = 'rst', implicit_namespaces: bool = False, package_name: Path | None = None) → Path[source]

Convert a sphinx-apidoc generated source file name into a nested directory based path, and rename to “index” files where necessary.

Parameters:

  • sphinx_source_file – Path to the sphinx-apidoc generated file.

  • package_dir – The directory to compare sphinx-apidoc generated file against.

  • extension – The extension of the sphinx-apidoc generated file.

  • implicit_namespaces – Whether to treat package_dir as a package. If False, any directory that does not contain __init__ file will be ignored.

  • package_name – Name of the directory to put all the package documentation in. This resides in the documentation directory. For example, it renames docs/myproj/a/b/c.rst to docs/newname/a/b/c.rst, where newname is the new name of the directory. If None, the name is derived from package_dir and sphinx source file.

Returns:

A string representing the path of the file.

sphinx_nested_apidoc.core.rename_files(sphinx_source_dir: Path, package_dir: Path, package_name: Path | None = None, extension: str = 'rst', implicit_namespaces: bool = False, dry_run: bool = False, force: bool = False, excluded_files: Iterable[str] = ('index', 'modules')) → None[source]

Renames the sphinx-apidoc generated files located in the source directory.

Parameters:

  • sphinx_source_dir – Path where the sphinx-apidoc generated files are located.

  • package_dir – The directory to compare sphinx-apidoc generated file against.

  • package_name – Name of the directory to put all the package documentation in. This resides in the documentation directory. For example, it renames docs/myproj/a/b/c.rst to docs/newname/a/b/c.rst, where newname is the new name of the directory. If None, the name is derived from package_dir and sphinx source file.

  • extension – The extension of the sphinx-apidoc generated file.

  • implicit_namespaces – Whether to treat package_dir as a package. If False, any directory that does not contain __init__ file will be ignored.

  • dry_run – Runs but does not actually rename the files.

  • force – Whether to replace files if they already exist.

  • excluded_files – Name of files (without extension) that should not be renamed/modified. By default, it excludes index and modules.