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
|
sphinx-apidoc
=============
Synopsis
--------
**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
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.
*sourcedir* is the path to a Python package to document, and *outputdir* is the
directory where the generated sources are placed. Any *pathnames* given are
paths to be excluded from the generation.
.. 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 <outputdir>
Directory to place the output files. If it does not exist, it is created.
.. option:: -f, --force
Force overwritting of any existing generated files.
.. option:: -l, --follow-links
Follow symbolic links.
.. 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.
.. 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`).
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)`
|
