---
name: "sphinx-apidoc"
section: "1"
platform: "linux"
package: "python-sphinx"
version: "9.1.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/sphinx-apidoc"
---

# sphinx-apidoc(1)

Sphinx API doc generator tool

## NAME

sphinx-apidoc - Sphinx API doc generator tool

## SYNOPSIS

**sphinx-apidoc** \[*OPTIONS*\] -o \<*OUTPUT\_PATH*\> \<*MODULE\_PATH*\> \[*EXCLUDE\_PATTERN* ...\]

## DESCRIPTION

**sphinx-apidoc** is a tool for automatic generation of Sphinx sources that, using the **autodoc** \<#module-sphinx.ext.autodoc\> extension, document a whole package in the style of other automatic API documentation tools.

*MODULE\_PATH* is the path to a Python package to document, and *OUTPUT\_PATH* is the directory where the generated sources are placed. Any *EXCLUDE\_PATTERN*s given are fnmatch-style \<https://docs.python.org/3/library/fnmatch.html\> file and/or directory patterns that will be excluded from generation.

**Warning:**

**sphinx-apidoc** generates source files that use **sphinx.ext.autodoc** \<#module-sphinx.ext.autodoc\> to document all found modules.  If any modules have side effects on import, these will be executed by **autodoc** when **sphinx-build** is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a **if \_\_name\_\_ == '\_\_main\_\_'** condition.

## OPTIONS

- **-o \<OUTPUT\_PATH\>**

  Directory to place the output files. If it does not exist, it is created.

- **-q**

  Do not output anything on standard output, only write warnings and errors to standard error.

- **-f, --force**

  Force overwriting of any existing generated files.

- **-l, --follow-links**

  Follow symbolic links. Defaults to **False**.

- **-n, --dry-run**

  Do not create or remove any files.

- **-s \<suffix\>**

  Suffix for the source files generated. Defaults to **rst**.

- **-d \<MAXDEPTH\>**

  Maximum depth for the generated table of contents file. Defaults to **4**.

- **--tocfile**

  Filename for a table of contents file. Defaults to **modules**.

- **-T, --no-toc**

  Do not create a table of contents file. Ignored when **--full** is provided.

- **--remove-old**

  Remove existing files in the output directory that are not created anymore. Not compatible with **--full**.

- **-F, --full**

  Generate a full Sphinx project (**conf.py**, **Makefile** etc.) using the same mechanism as **sphinx-quickstart**.

- **-e, --separate**

  Put documentation for each module on its own page.

  Added in version 1.2.

- **-E, --no-headings**

  Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings.

- **-P, --private**

  Include "\_private" modules.

  Added in version 1.2.

- **--implicit-namespaces**

  Without this option, **sphinx-apidoc** searches **sys.path** \<https://docs.python.org/3/library/sys.html#sys.path\> for Python packages containing **\_\_init\_\_.py** files, or single-file Python modules.

  This option instead uses **PEP 420** \<https://peps.python.org/pep-0420/\> implicit namespaces that allow layouts paths such as **foo/bar/module.py** or **foo/bar/baz/\_\_init\_\_.py** (note that **bar** and **foo** are namespaces, not modules).

- **-M, --module-first**

  Put module documentation before submodule documentation.

These options are used when **--full** is specified:

- **-a**

  Append module\_path to sys.path.

- **-H \<project\>**

  Sets the project name to put in generated files (see **project** \<#confval-project\>).

- **-A \<author\>**

  Sets the author name(s) to put in generated files (see **copyright** \<#confval-copyright\>).

- **-V \<version\>**

  Sets the project version to put in generated files (see **version** \<#confval-version\>).

- **-R \<release\>**

  Sets the project release to put in generated files (see **release** \<#confval-release\>).

Project templating

Added in version 2.2: Project templating options for sphinx-apidoc

- **-t, --templatedir=TEMPLATEDIR**

  Template directory for template files.  You can modify the templates of sphinx project files generated by apidoc.  Following Jinja2 template files are allowed:

  - •

    **module.rst.jinja**

  - •

    **package.rst.jinja**

  - •

    **toc.rst.jinja**

  - •

    **root\_doc.rst.jinja**

  - •

    **conf.py.jinja**

  - •

    **Makefile.jinja**

  - •

    **Makefile.new.jinja**

  - •

    **make.bat.jinja**

  - •

    **make.bat.new.jinja**

  In detail, please refer the system template files Sphinx provides. (**sphinx/templates/apidoc** and **sphinx/templates/quickstart**)

## ENVIRONMENT

- **SPHINX\_APIDOC\_OPTIONS**

  A comma-separated list of option to append to generated **automodule** directives. Defaults to **members,undoc-members,show-inheritance**.

## SEE ALSO

**[sphinx-build(1)](/sphinx-build/1.md)**, **[sphinx-autogen(1)](/sphinx-autogen/1.md)**

## Copyright

2007-2026, the Sphinx developers