10

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

Improve this question
4
  • What other projects have you looked at that have a separate page for each function? Commented Apr 12, 2017 at 5:23
  • @mzjn see networkx.readthedocs.io/en/stable/reference/algorithms.html Commented Apr 12, 2017 at 15:50
  • That documentation uses the same approach with autosummary as I suggest in my answer. See github.com/networkx/networkx/blob/v1.11/doc/source/reference/… Commented Apr 12, 2017 at 15:54
  • .. automodule:: ../EoN is ill-formed. The argument to that directive or to the currentmodule directive should be a "dotted module name", such as simply EoN or mypackage.EoN. ../EoN is not a correct module name. Commented Apr 12, 2017 at 16:39

2 Answers 2

Reset to default
11

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

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

Hi @astrofrog - it looks like this has been useful to people, but I haven't tried it - mostly because I don't know where to put this line. Can you tell me exactly what I should be doing? (and fwiw, my package is at github.com/springer-math/Mathematics-of-Epidemics-on-Networks if that helps you fine-tune any advice)
@Joel - you would need to put extensions = ['sphinx_automodapi.automodapi'] in conf.py, and .. automodapi:: EoN inside index.rst.
This package is seriously awesome. Thank you for sharing it. I used .. automodsumm:: module, :toctree: api to make a table without separate function/class sections.
I like the use of automodapi, but was curious if there is a way to specify the classes that should be displayed. Basically the opposite of :skip: str (which allows us to remove unnecessary entries); is there any option to specify what we want included? I see that this is possible via autosummary, but given a choice, I would like to use automodapi.
Finally! This is what I was looking for! It was really hard to find it, though. Thank you very much @astrofrog
6

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

Improve this answer

7 Comments

Getting an error when I try that - WARNING: [autosummary] failed to import u'fast_SIR': no module named fast_SIR I've edited the question showing exactly how I've implemented your answer (too much information to squeeze into a comment).
I'm still not having luck. It's giving an error that it can't find the module EoN.my_function1. Which of course it can't because it's a function. Could it be related to the fact that your answer in the linked question included a template?
I don't think the template is the problem. When no template option is given, the default template is used: autosummary/base.rst.
I found your project on GitHub. The currentmodule argument should be EoN.simulation for autosummary to work. And there should be a blank line immediately after :toctree: functions (raw.githubusercontent.com/EpidemicsOnNetworks/…).
I've put up the most recent attempt up on github. If you look at my docs/documentation.rst, I believe everything you've said is in place. But I continue to get the error "failed to import 'EoN.simulation.fast_SIR': no module named EoN.simulation.fast_SIR" when that is the function I want to get.
|

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.