CODEWITHSUNDEEP
pythonpython-sphinxread-the-docs
Joel
Joel

Reputation: 23827

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

Upvotes: 10

Views: 10528

Answers (2)

astrofrog
astrofrog

Reputation: 34091

I think the sphinx-automodapi Sphinx extension may do what you need. Essentially to document a module you would just do:

.. automodapi:: mypackage.mymodule

and it will generate the table and individual pages for each function.

Disclaimer: I am an author of sphinx-automodapi

Upvotes: 11

mzjn
mzjn

Reputation: 50957

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

Upvotes: 6

Related Questions