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).
Related
I am generating documentation for a Python project using the Sphinx autodocsumm extension with the following autosummary configuration to show a summary of only classes at the beginning of the document.
Module1 module
----------------------------
.. automodule:: src.Module1
:members:
:undoc-members:
:show-inheritance:
:autosummary:
:autosummary-no-nesting:
In the generated html, the summary class name hyperlinks are not consistent -- one is a path to a separate summary stub file, while the other just references an anchor in the main src.html file.
file:///project_path/docs/_build/html/src.Module1/src.Module1.Class1.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2
I can't figure out why the classes are being treated differently during the make. The first one is a large class with many members while the second is a small class with just a few lines, so maybe there is some threshold for generating the stub file? My preference is to not reference a separate file and only jump to the respective anchor within the main document for all summary links.
Is there a setting to control this behavior?
Edit: Upon further review, I don't think this has anything to do with autodocsumm after all. I notice after doing the "make html" a subfolder is create only for the Class1 documentation while Class2 is referenced only in the main src.html file.
project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html
So... Why are these two classes treated differently? Also, is there any setting to prevent a separate folder and html file from being generated?
I finally figured out the issue... While narrowing my project down to a minimum reproducible example, I noticed an src.Module1 folder under docs that had rst files for Class1 only.
Project
docs
_build
src.Module1
Module1.Class1.rst
src.Module1.Class1.rst
I'm not sure what I did to produced that folder, but after deleting it and rebuilding the Sphinx html, I am now getting the document anchors I expect directly in the src.html file:
file:///project_path/docs/_build/html/src.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2
I am facing the same problem as in this thread. When I build my Sphinx documentation with make html then I get a lot of warnings like this
None:None: WARNING: toctree contains reference to nonexisting document u'cars.Car.time_elapsed'
I am using html_theme = 'sphinx_rtd_theme'. If I change it to classic, then I don't get the warnings. If I add numpydoc_show_class_members = False to conf.py, then I don't get them either.
BUT; I really like sphinx_rtd_theme and when I use classic or add numpydoc_show_class_members = False, then a 'TOC' of my Python methods are removed, which I prefer staying (see the red box in the image) .
The documentation of the cars module is made by
.. automodule:: cars
:members:
The module contains a single class Car with two methods. The docstrings are written in numpydoc.
It seems to me that you are currently using the numpydoc extension. Please note that Numpy and Google style docstrings are now supported by the builtin sphinx.ext.napoleon extension.
Removing the numpydoc extension and using sphinx.ext.napoleon will likely solve your problem.
Sources
Napoleon - Marching toward legible docstrings
Sphinx Doc - Support for NumPy and Google style docstrings
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!
I'm using sphinx-apidoc and autosummary extensions to document an API for a library and I'm really unable to understand the purpose of the generated/ option below:
.. autosummary::
:nosignatures:
:toctree: generated/
module.function_1
module.function_2
...
I've seen this is the Sphinx documentation, and in libraries like pandas. I'm using toctree and my API is autogenerating, but I don't understand what generated is. I don't see a folder called generated, and don't know what the advantage/purpose of this is.
Thanks
The "generated" option is the name of the output directory where Sphinx puts automatically generated "stub" .rst files. It does not have to be called "generated"; you can use any name.
When the autosummary_generate configuration variable is set to True, Sphinx generates a .rst file for each entry listed in autosummary directives. For example, if you are documenting a module with several classes, this feature can be used to put the full documentation for each class on a separate page. The autosummary table will contain links to these pages.
The Sphinx templates I use (for example sphninxdoc or sphinx13) have a link to a 'contents.rst' file; however, though this file is documented as "special", I don't see a way to generate it.
Is there a way to get Sphinx to generate 'contents.rst' automatically, or do I need to generate it manually?
When I came to this page, I needed to fix the .readthedocs.yml. My sphinx configuration path was missing the "source" part:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
Within the config, I have
# The master toctree document.
master_doc = 'index'
The "special" contents.rst file that is mentioned in the question is not generated automatically. It is written like any other reST file and is stored in the Python repository: https://github.com/python/cpython/blob/master/Doc/contents.rst.
The Python documentation main page at http://docs.python.org/release/2.7/index.html has a Complete Table of Contents link that points to contents.html, which is built from contents.rst.
The source for the Sphinx documentation includes a similar contents.rst: https://github.com/sphinx-doc/sphinx/blob/master/doc/contents.rst.