Sphinx

# sphinx-apidoc

## 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` 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_PATTERNs given are fnmatch-style file and/or directory patterns that will be excluded from generation.

Warning

`sphinx-apidoc` generates source files that use `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` for Python packages containing `__init__.py` files, or single-file Python modules.

  This option instead uses PEP 420 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`).

-A <author>

  Sets the author name(s) to put in generated files (see `copyright`).

-V <version>

  Sets the project version to put in generated files (see `version`).

-R <release>

  Sets the project release to put in generated files (see `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-autogen(1)