summaryrefslogtreecommitdiffstats
path: root/doc/man/sphinx-autogen.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/man/sphinx-autogen.rst
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/man/sphinx-autogen.rst')
-rw-r--r--doc/man/sphinx-autogen.rst97
1 files changed, 97 insertions, 0 deletions
diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst
new file mode 100644
index 0000000..caeb44b
--- /dev/null
+++ b/doc/man/sphinx-autogen.rst
@@ -0,0 +1,97 @@
+sphinx-autogen
+==============
+
+Synopsis
+--------
+
+**sphinx-autogen** [*options*] <sourcefile> ...
+
+Description
+-----------
+
+:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included
+in :rst:dir:`autosummary` listing(s).
+
+*sourcefile* is the path to one or more reStructuredText documents containing
+:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
+can be an :py:mod:`fnmatch`-style pattern.
+
+Options
+-------
+
+.. program:: sphinx-autogen
+
+.. option:: -o <outputdir>
+
+ Directory to place the output file. If it does not exist, it is created.
+ Defaults to the value passed to the ``:toctree:`` option.
+
+.. option:: -s <suffix>, --suffix <suffix>
+
+ Default suffix to use for generated files. Defaults to ``rst``.
+
+.. option:: -t <templates>, --templates <templates>
+
+ Custom template directory. Defaults to ``None``.
+
+.. option:: -i, --imported-members
+
+ Document imported members.
+
+.. option:: -a, --respect-module-all
+
+ Document exactly the members in a module's ``__all__`` attribute.
+
+Example
+-------
+
+Given the following directory structure::
+
+ docs
+ ├── index.rst
+ └── ...
+ foobar
+ ├── foo
+ │ └── __init__.py
+ └── bar
+ ├── __init__.py
+ └── baz
+ └── __init__.py
+
+and assuming ``docs/index.rst`` contained the following:
+
+.. code-block:: rst
+
+ Modules
+ =======
+
+ .. autosummary::
+ :toctree: modules
+
+ foobar.foo
+ foobar.bar
+ foobar.bar.baz
+
+If you run the following:
+
+.. code-block:: console
+
+ $ PYTHONPATH=. sphinx-autogen docs/index.rst
+
+then the following stub files will be created in ``docs``::
+
+ docs
+ ├── index.rst
+ └── modules
+ ├── foobar.bar.rst
+ ├── foobar.bar.baz.rst
+ └── foobar.foo.rst
+
+and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive
+and some other information.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)`