summaryrefslogtreecommitdiffstats
path: root/doc/man/sphinx-apidoc.rst
blob: efc8230dc6db0a35640ee4b0da1120250fd558e4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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 :py:mod:`~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`_ 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 <OUTPUT_PATH>

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

.. option:: -q

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

.. option:: -f, --force

   Force overwriting of any existing generated files.

.. option:: -l, --follow-links

   Follow symbolic links. Defaults to ``False``.

.. option:: -n, --dry-run

   Do not create any files.

.. option:: -s <suffix>

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

.. option:: -d <MAXDEPTH>

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

.. 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 <project>

   Sets the project name to put in generated files (see :confval:`project`).

.. option:: -A <author>

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

.. option:: -V <version>

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

.. option:: -R <release>

   Sets the project release to put in generated files (see :confval:`release`).

.. rubric:: Project templating

.. versionadded:: 2.2
   Project templating options for sphinx-apidoc

.. option:: -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_t``
   * ``package.rst_t``
   * ``toc.rst_t``
   * ``root_doc.rst_t``
   * ``conf.py_t``
   * ``Makefile_t``
   * ``Makefile.new_t``
   * ``make.bat_t``
   * ``make.bat.new_t``

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

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