1SPHINX-APIDOC(1) Sphinx SPHINX-APIDOC(1)
2
6 sphinx-apidoc - Sphinx API doc generator tool
7
9 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN
10 …]
11
13 sphinx-apidoc is a tool for automatic generation of Sphinx sources
14 that, using the autodoc extension, document a whole package in the
15 style of other automatic API documentation tools.
16 MODULE_PATH is the path to a Python package to document, and OUT‐
18 PUT_PATH is the directory where the generated sources are placed. Any
19 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
20 that will be excluded from generation.
21 WARNING:
23 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
24 document all found modules. If any modules have side effects on
25 import, these will be executed by autodoc when sphinx-build is run.
26 If you document scripts (as opposed to library modules), make sure
28 their main routine is protected by a if __name__ == '__main__' con‐
29 dition.
30
32 -o <OUTPUT_PATH>
33 Directory to place the output files. If it does not exist, it is
34 created.
35 -q Do not output anything on standard output, only write warnings
37 and errors to standard error.
38 -f, --force
40 Force overwriting of any existing generated files.
41 -l, --follow-links
43 Follow symbolic links.
44 -n, --dry-run
46 Do not create any files.
47 -s <suffix>
49 Suffix for the source files generated. Defaults to rst.
50 -d <MAXDEPTH>
52 Maximum depth for the generated table of contents file.
53 --tocfile
55 Filename for a table of contents file. Defaults to modules.
56 -T, --no-toc
58 Do not create a table of contents file. Ignored when --full is
59 provided.
60 -F, --full
62 Generate a full Sphinx project (conf.py, Makefile etc.) using
63 the same mechanism as sphinx-quickstart.
64 -e, --separate
66 Put documentation for each module on its own page.
67 New in version 1.2.
69 -E, --no-headings
72 Do not create headings for the modules/packages. This is useful,
73 for example, when docstrings already contain headings.
74 -P, --private
76 Include “_private” modules.
77 New in version 1.2.
79 --implicit-namespaces
82 By default sphinx-apidoc processes sys.path searching for mod‐
83 ules only. Python 3.3 introduced PEP 420 implicit namespaces
84 that allow module path structures such as foo/bar/module.py or
85 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
86 not modules).
87 Interpret paths recursively according to PEP-0420.
89 -M, --module-first
91 Put module documentation before submodule documentation.
92 These options are used when --full is specified:
94 -a Append module_path to sys.path.
96 -H <project>
98 Sets the project name to put in generated files (see project).
99 -A <author>
101 Sets the author name(s) to put in generated files (see copy‐
102 right).
103 -V <version>
105 Sets the project version to put in generated files (see ver‐
106 sion).
107 -R <release>
109 Sets the project release to put in generated files (see
110 release).
111 Project templating
113 New in version 2.2: Project templating options for sphinx-apidoc
115 -t, --templatedir=TEMPLATEDIR
118 Template directory for template files. You can modify the tem‐
119 plates of sphinx project files generated by apidoc. Following
120 Jinja2 template files are allowed:
121 · module.rst_t
123 · package.rst_t
125 · toc.rst_t
127 · master_doc.rst_t
129 · conf.py_t
131 · Makefile_t
133 · Makefile.new_t
135 · make.bat_t
137 · make.bat.new_t
139 In detail, please refer the system template files Sphinx pro‐
141 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
142 start)
143
145 SPHINX_APIDOC_OPTIONS
146 A comma-separated list of option to append to generated automod‐
147 ule directives. Defaults to members,undoc-members,show-inheri‐
148 tance.
149
151 sphinx-build(1), sphinx-autogen(1)
152
154 2007-2020, Georg Brandl and the Sphinx team
1553.2.1 Aug 18, 2020 SPHINX-APIDOC(1)