sphinx-apidoc ============= Synopsis -------- **sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*> [*EXCLUDE_PATTERN*, ...] Description ----------- :program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources that, using the :rst:dir:`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`_ file and/or directory patterns that will be excluded from generation. .. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html .. warning:: ``sphinx-apidoc`` generates source files that use :mod:`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 ------- .. program:: sphinx-apidoc .. option:: -o Directory to place the output files. If it does not exist, it is created. .. option:: -f, --force Force overwriting of any existing generated files. .. option:: -l, --follow-links Follow symbolic links. .. option:: -n, --dry-run Do not create any files. .. option:: -s Suffix for the source files generated. Defaults to ``rst``. .. option:: -d Maximum depth for the generated table of contents file. .. option:: --tocfile Filename for a table of contents file. Defaults to ``modules``. .. option:: -T, --no-toc Do not create a table of contents file. Ignored when :option:`--full` is provided. .. option:: -F, --full Generate a full Sphinx project (``conf.py``, ``Makefile`` etc.) using the same mechanism as :program:`sphinx-quickstart`. .. option:: -e, --separate Put documentation for each module on its own page. .. versionadded:: 1.2 .. option:: -E, --no-headings Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings. .. option:: -P, --private Include "_private" modules. .. versionadded:: 1.2 .. option:: --implicit-namespaces By default sphinx-apidoc processes sys.path searching for modules only. Python 3.3 introduced :pep:`420` implicit namespaces that allow module path structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py`` (notice that ``bar`` and ``foo`` are namespaces, not modules). Interpret paths recursively according to PEP-0420. .. option:: -M, --module-first Put module documentation before submodule documentation. These options are used when :option:`--full` is specified: .. option:: -a Append module_path to sys.path. .. option:: -H Sets the project name to put in generated files (see :confval:`project`). .. option:: -A Sets the author name(s) to put in generated files (see :confval:`copyright`). .. option:: -V Sets the project version to put in generated files (see :confval:`version`). .. option:: -R Sets the project release to put in generated files (see :confval:`release`). Environment ----------- .. envvar:: SPHINX_APIDOC_OPTIONS A comma-separated list of option to append to generated ``automodule`` directives. Defaults to ``members,undoc-members,show-inheritance``. See also -------- :manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)` .. _fnmatch: https://docs.python.org/3/library/fnmatch.html