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:'
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 building my documentation with Sphinx, to use with readthedocs.io. So far this always worked well. I'm orienting myself at the (in my opinion) excellent documentation of the godot engine.
Since I appreciated the titles in the documentation of the godot documentation, I tried to replicate these, by first having a look at the way they did it. Here's the link to the source for their index file. (Note: the relevant section is at the end of the document)
This seemed reasonable, as they used multiple toctrees, to give every toctree a caption.
When I do the same however, sphinx seems to automatically number my sections, something I do not want. The toctrees do not contain the :numbered: tag.
Here's a code sample, explaining how my toctrees are structured in principle:
.. toctree::
:caption: Section 1
Entry1
Entry2
.. toctree::
:caption: Section 2
Entry2
The expected result would be similar to the godot documentation, with sections having titles but no numbers. Instead I am getting numbers, which seem arbitrary to me:
Section1
1.Entry1
2.Entry2
Section2
1.Entry1
I can't find anything in the godot documentation explaining why they do not have these numbers, and I can't find any mention of it in the Sphinx toctree documentation either.
Any help or pointers towards help are greatly appreciated, thank you for your time.
Edit:
Uploading the repo, with the built static html files to readthedocs.io seems to remove/fix the numbering. It persists in the local built though (the index.html file I built with sphinx in the first place).
The answer to the question, courtesy of mzjn (see comment thread):
A rebuild of the project solved the issue. This can be done by entering
make clean html
in the console, fixing the weird numbering issue.
The relevant github issue can be found here.
This may possibly be caused by sphinx trying to find changes in the code and update these, instead of rebuilding the project every time. In this instance it did not update the toctree correctly.
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).
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've used .. automodule:: mypath.mymodule in my documentation. I wanted the plain module docstring with no other information for members. The module docstring appears, however no indication of the name of the module and no special paragraph formatting.
Is there a standard way to include the name of the actual module and maybe emphasis that particular paragraph as to distinguish it from normal text?
I'd say that the "standard" way is to add a heading with the module name:
mypath.mymodule
===============
.. automodule:: mypath.mymodule
Examples from some packages (click on "Show Source" to see the reST markup):
Celery: http://docs.celeryproject.org/en/latest/reference/celery.events.html
PyMongo: http://api.mongodb.org/python/current/api/bson/index.html
matplotlib: http://matplotlib.org/api/dates_api.html