Develop Reference

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

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

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

Automatically create a toctree for autodoc classes in Sphinx

I'm looking to increase the documentation in one of my libraries. I've been using sphinx to help build the documentation and recently started exploring the autodoc extension.
It seems like in most professional documentation, each class documentation page has a list of all the documented methods with links at the top. Or, in other words, a toctree at the top with hyperlinks to each of the more in depth method documentation.
Is there a way to automatically create this toctree for each of the classes being documented with autodoc?

In your conf.py file for sphinx add
extensions = ['sphinx.ext.autosummary',]
# NOTE: Don't overwrite your old extension list! Just add to it!
autodoc_default_flags = ['members']
autosummary_generate = True
I put the toctree in my index.rst, and it looks like this:
.. autosummary::
:toctree: stubs
Class1
Class2
Class3
See this example for the conf.py settings
and this example for an example of the toctree.
Hope that helps!

sphinx generate class modules overview

I'd like sphinx to generate a module overview similar to the one generated by doxygen, here is an example
I can't find how sphinx can do that
I could use Graphviz to generate some sort of graph, but I can't find a way to get a clickable object in the graph that operates in the same way as the example above.
Is there any way to do that in sphinx directly or some hack to make it work as the doxygen module overview?

Sphinx has a built-in extension called sphinx.ext.inheritance_diagram that uses Graphviz. It defines one directive: inheritance-diagram. Here is an example of how you could use it in an .rst file:
.. inheritance-diagram:: mymodule.MyClass1 mymodule.MyClass2
:parts: 1
Here are some examples of inheritance diagrams in documents generated by Sphinx:
http://matplotlib.org/1.3.1/devel/documenting_mpl.html#inheritance-diagrams
http://openalea.gforge.inria.fr/doc/vplants/PlantGL/doc/_build/html/user/math.html#class-inheritance-diagram
There is also a "generic" sphinx.ext.graphviz extension for embedding graphs in documentation.

Sphinx autosummary "toctree contains reference to nonexisting document" warnings

I am trying to automatically create api docs for a large python codebase using Sphinx.
I have tried using build_modules.py and sphinx-apidoc. With either one, I can get rst docs successfully created in my output directory for the packages and top-level modules.
However, when I build using
make html
it gives thousands of errors of this type:
<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'
for every single class and method in the codebase.
With some experimentation I think I have discovered that the autosummary/autoclass directives are creating toctrees that expect there to be rst files for every class and method.
Other than the warnings, the documentation seems to work well, but I would like to get rid of them and I think I may have misconfigured something.
I have also tried nipype/tools to much the same effect.
I modified apigen.py and build_modref_templates.py to create rst stubs for each of these "missing" documents, with autoclass/autofunction/automethods as appropriate. However, the build takes quite a long time (10 minutes) and eventually crashes due to memory errors on the last build step.
Here is an example module rst file that creates all the warnings:
src Package
===========
:mod:`src` Package
------------------
.. automodule:: src.__init__
:members:
:undoc-members:
:show-inheritance:
:mod:`Example1` Module
------------------------------------
.. automodule:: src.Example1
:members:
:undoc-members:
:show-inheritance:
:mod:`Example2` Module
------------------
.. automodule:: src.Example2
:members:
:undoc-members:
:show-inheritance:
Thanks for any advice on how to make these warnings resolve! I would like to stay away from any solution that involves modifying the sphinx site-package files.

Sorry for such a late answer (if it can be considered that) but I found this link that discusses what may be happening to you:
https://github.com/phn/pytpm/issues/3#issuecomment-12133978
The idea that if you have some special Doc scraper in your documentation code that is building autosummary documentation after autosummary has already run may be something to look into if you are still having this issue. Although, I'm not sure how much help this will be.
The key from the link is to add: numpydoc_show_class_members = False to conf.py

I just encountered this issue too and spend hours on this, The following worked for me:
Sphinx can be fussy, and sometimes about things you weren’t expecting.
For example, you well encounter something like:
WARNING: toctree contains reference to nonexisting document u'all-about-me'
...
checking consistency...
<your repository>/my-first-docs/docs/all-about-me.rst::
WARNING: document isn't included in any toctree'
Quite likely, what has happened here is that you indented all-about-me in your .. toctree:: with four spaces, when Sphinx is expecting three.
Source: docs!

If you are using the numpydoc extension, you could consider removing it and using sphinx.ext.napoleon instead.
Since version 1.3, Numpy and Google style docstrings are in fact supported by this builtin extension.
Removing numpydoc and using sphinx.ext.napoleon in your conf.py will therefore probably solve your problem.
Sources
Napoleon - Marching toward legible docstrings
Sphinx Doc - Support for NumPy and Google style docstrings

In Sphinx 5.3, your indentation needs to be consistent (the number of spaces does not seem to matter).
Three space indentation will work:
.. toctree::
:maxdepth: 2
:caption: Contents:
admin/index
Two space indentation will also work:
.. toctree::
:maxdepth: 2
:caption: Contents:
admin/index
However if the indentation is inconsitent, with :maxdepth: indented with three spaces, but admin/index indented with two spaces as shown below...
.. toctree::
:maxdepth: 2
:caption: Contents:
admin/index
...then you will likely get warnings:
WARNING: toctree contains reference to nonexisting document ' :maxdepth: 2'
WARNING: toctree contains reference to nonexisting document ' :caption: Contents:'

Parsing .rst files with Sphinx-specific directives programmatically

I would like to be able to parse sphinx based rst in Python for further processing and checking. Something like:
import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)
It seems that something is possible in docutils using the docutils.core.publish_file:
publish_file(open("/path/to/file.rst")
But that doesn't know anything about sphinx specific directives etc...

You can use Sphinx Extensions to do custom processing before the final write. There is a very good getting started example project in the documentation that discusses various hooks that allow you to customize Sphinx.
Depending on what you're trying to do, you may need to supply your do_something function as a call back argument to one of these events.
doctree-resolved(app, doctree, docname)
html-page-context(app, pagename, templatename, context, doctree)
And then you can extend sphinx as follows
def setup(app):
app.connect('doctree-resolved', do_something)
If the example in the Sphinx tutorial is not detailed enough, Doug Hellmann also has a blog post about creating a spell checker for Sphinx. I found it to be a useful reference for the Sphinx extension I had to write a while back.