diff --git a/doc/conf.py b/doc/conf.py index 62c5c13d5..db2846186 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -84,6 +84,8 @@ man_pages = [ 'template generator', '', 1), ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool', '', 1), + ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages', + '', 1), ] texinfo_documents = [ diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index d2e94e7da..7adf65c53 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -125,6 +125,9 @@ text of the form:: If the ``-o`` option is not given, the script will place the output files in the directories specified in the ``:toctree:`` options. +For more information, refer to the :doc:`sphinx-autogen documentation +` + Generating stub pages automatically ----------------------------------- diff --git a/doc/man/index.rst b/doc/man/index.rst index 5d0e2c035..c2ca3f065 100644 --- a/doc/man/index.rst +++ b/doc/man/index.rst @@ -19,3 +19,4 @@ Additional Applications :maxdepth: 3 sphinx-apidoc + sphinx-autogen diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst index 4586d43f5..145c53648 100644 --- a/doc/man/sphinx-apidoc.rst +++ b/doc/man/sphinx-apidoc.rst @@ -121,7 +121,7 @@ These options are used when :option:`--full` is specified: See also -------- -:manpage:`sphinx-build(1)` +:manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)` Author ------ diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst new file mode 100644 index 000000000..dcab68d76 --- /dev/null +++ b/doc/man/sphinx-autogen.rst @@ -0,0 +1,93 @@ +sphinx-autogen +============== + +Synopsis +-------- + +**sphinx-autogen** [*options*] ... + +Description +----------- + +:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources +that, using the :rst:dir:`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:module:`fnmatch`-style pattern. + +Options +------- + +.. program:: sphinx-autogen + +.. option:: -o + + 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 + + Default suffix to use for generated files. Defaults to ``rst``. + +.. option:: -t , --templates + + Custom template directory. Defaults to ``None``. + +.. option:: -i, --imported-members + + Document imported members. + +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:: bash + + $ sphinx-autodoc doc/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 :rst:dir:`autodoc` directive and some +other information. + +See also +-------- + +:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)`