sphinx/doc/man/sphinx-autogen.rst

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.

.. option:: --remove-old

   Remove existing files in the output directory
   that are not generated anymore.

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)`