auto_api_doc

Automatic API reference documentation generator for Sphinx.

While Sphinx’s autodoc extension lets you document Python modules, it still requires manually including each module and defining members in your documentation. This module automates that process by scanning your entire package structure and generating the necessary .rst files with proper autodoc directives for all modules and packages. It supports ignoring specific modules or packages through pattern matching, allowing you to exclude internal, private, or third-party code from your documentation.

docfly.auto_api_doc.normalize_ignore_patterns(patterns: list[str]) → list[str]

Normalize ignore patterns by removing .py extensions.

Parameters:

patterns – List of patterns to normalize

Returns:

List of normalized patterns

docfly.auto_api_doc.should_ignore(fullname: str, normalized_patterns: list[str]) → bool

Determine if a module or package should be ignored based on its name.

Checks if the module or package fullname matches any of the ignore patterns. A match occurs when the fullname starts with any pattern in the list.

Parameters:

• fullname – Full name of the module or package (e.g., “docfly.auto_api_doc”)

• normalized_patterns – List of normalized ignore patterns

Returns:

True if the module/package should be ignored, False otherwise

Examples: >>> should_ignore(“docfly.vendor”, [“docfly.vendor”]) True

>>> should_ignore("docfly.vendor.picage", ["docfly.vendor"])
True

>>> should_ignore("docfly.auto_api_doc", ["docfly.vendor"])
False

>>> should_ignore("docfly.tests", ["docfly.tests", "docfly.vendor"])
True

>>> should_ignore("docfly._version", ["docfly._"])
True

docfly.auto_api_doc.write_file(path: Path, text: str)

Write text to a file, creating parent directories if needed.

class docfly.auto_api_doc.ApiDocGenerator(dir_output: ~pathlib.Path, package_name: str, ignore_patterns: list[str] = <factory>)

Generator for Sphinx API reference documentation.

This class traverses a Python package structure and generates .rst files with appropriate autodoc directives for each module and package. The generated files maintain the package hierarchy and can be directly included in Sphinx documentation.

Example generated autodoc code:

/path/to/dir_output/package
/path/to/dir_output/package/subpackage1
/path/to/dir_output/package/subpackage1/__init__.rst
/path/to/dir_output/package/subpackage1/module.rst
/path/to/dir_output/package/subpackage2/
/path/to/dir_output/package/subpackage2/__init__.rst
/path/to/dir_output/package/subpackage2/module.rst
/path/to/dir_output/package/__init__.rst
/path/to/dir_output/package/module1.rst
/path/to/dir_output/package/module2.rst

Parameters:

• dir_output –

  Directory where generated .rst files will be written. Usually it is next to the sphinx doc conf.py file. For example, if your conf.py file is at docs/source/conf.py, and your package name is docfly, you should set dir_output to docs/source/api. Then the autodoc code looks like:

  /docs/source/api/docfly
  /docs/source/api/docfly/__init__.rst
  /docs/source/api/docfly/module1.rst
  /docs/source/api/docfly/module2.rst
  /docs/source/api/docfly/...
  

• package_name – Name of the package to document.

• ignore_patterns – List of patterns for modules/packages to ignore. See should_ignore() for details on how patterns are matched.

property package: Package

Get the package object for the specified package name.

fly(cleanup_before_fly: bool = True)

Generate the API documentation .rst files.

Traverses the package structure and creates .rst files for each package and module. Each package gets an __init__.rst file that includes links to its sub-packages and modules.

Parameters:

cleanup_before_fly – If True, remove existing output directory before generating new documentation