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

Joel
  • 22,598
  • 6
  • 69
  • 93
  • What other projects have you looked at that have a separate page for each function? – mzjn Apr 12 '17 at 05:23
  • @mzjn see https://networkx.readthedocs.io/en/stable/reference/algorithms.html – Joel Apr 12 '17 at 15:50
  • That documentation uses the same approach with autosummary as I suggest in my answer. See https://github.com/networkx/networkx/blob/v1.11/doc/source/reference/algorithms.bipartite.rst – mzjn Apr 12 '17 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. – mzjn Apr 12 '17 at 16:39

2 Answers2

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

mzjn
  • 48,958
  • 13
  • 128
  • 248
astrofrog
  • 32,883
  • 32
  • 90
  • 131
  • 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 https://github.com/springer-math/Mathematics-of-Epidemics-on-Networks if that helps you fine-tune any advice) – Joel Feb 20 '19 at 01:25
  • @Joel - you would need to put ``extensions = ['sphinx_automodapi.automodapi']`` in ``conf.py``, and ``.. automodapi:: EoN`` inside ``index.rst``. – astrofrog Feb 22 '19 at 08:27
  • 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. – Luke Davis Feb 22 '19 at 22:44
  • 1
    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`. – Shailesh Appukuttan Dec 18 '19 at 16:13
  • Finally! This is what I was looking for! It was really hard to find it, though. Thank you very much @astrofrog – John Reds Jun 17 '21 at 13:37
5

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

Community
  • 1
  • 1
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • 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). – Joel Apr 12 '17 at 16:33
  • 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? – Joel Apr 24 '17 at 19:03
  • I don't think the template is the problem. When no `template` option is given, the default template is used: [autosummary/base.rst](http://www.sphinx-doc.org/en/stable/ext/autosummary.html#customizing-templates). – mzjn Apr 24 '17 at 19:22
  • 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` (https://raw.githubusercontent.com/EpidemicsOnNetworks/EpidemicsOnNetworks/master/docs/methods.rst). – mzjn Apr 24 '17 at 19:50
  • 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. – Joel Apr 24 '17 at 20:26
  • You must add the `sphinx.ext.autosummary` extension to the `extensions` variable in conf.py. – mzjn Apr 24 '17 at 20:31
  • Likely that last thing was the solution. At any rate, sphinx-autogen continues to give me that error message but sphinx-autobuild is now creating the files I want (it's possible I missed them being created a step or two earlier since I was focused on the error message from sphinx-autogen). – Joel Apr 24 '17 at 21:43