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
|
