Search code examples
pythonpython-sphinxread-the-docs

Using Sphinx to automatically generate a separate document for each function

I've been building a Python module with many different functions.

I'm using Sphinx and readthedocs to provide documentation. I've made decent progress, but currently I have one massive page that gives the documentation for all of my functions (in alphabetical order).

I've looked at other projects which have a separate page for each function. In looking through their source, I find a separate .rst file has been created for each. I assume this is done automatically, and this page on generating autodoc summaries seems like it's describing some of this, but I just can't make sense of it.

sphinx-apidoc has an option (-e) to create a page for each module, but I want one for each function.

How does one use Sphinx to automatically generate a separate page for each function?

additional information

To add info for one of the answers below, I've put the following into my EoN.rst file, which sits in the subdirectory docs.

EON documentation
=================

.. automodule:: ../EoN
   :members:

.. currentmodule:: ../EoN

.. autosummary::
   :toctree: functions

   fast_SIR
   fast_SIS

I get the error message 

$ sphinx-autogen -o docs/generated docs/*.rst

[autosummary] generating autosummary for: docs/index.rst, docs/methods.rst, docs/quickstart.rst

[autosummary] writing to docs/generated

WARNING: [autosummary] failed to import u'fast_SIR': no module named fast_SIR

WARNING: [autosummary] failed to import u'fast_SIS': no module named fast_SIS

fast_SIS and fast_SIR sit within ../EoN.py

Solution

  • In the answer to Sorting display by class using sphinx with 'autodoc'? it is explained how to generate documentation for classes with one page per class, using autosummary with autosummary_generate=True.

    This mechanism works for functions too. Use something like this:

    EoN API documentation
=====================

.. currentmodule:: EoN

.. autosummary::
   :toctree: functions

   my_function1
   my_function2
   my_function3
   ...

    You have to enumerate each function in the autosummary directive, but the corresponding *.rst files are generated automatically (in the functions subdirectory).