Genindex And Modindex Footer Links Don't Work In Readthedocs.io

I have a Python project using Sphinx for docs. I am building the docs remotely on readthedocs.io service. I used sphinx-quickstart and it generated an index.rst file with these lin

Solution 1:

genindex and modindex are automatically managed by Sphinx. Two cases should be considered:

1. Any declaration in a .rst file will be inserted in those indexes. For example, if you declare a function from the Python domain:

Your rst file
-------------

.. py:function:: name(parameters)

It will be inserted in the indexes even if it doesn't have a corresponding function in any .py file.

2. Using autodoc directives, the same applies with a few more rules. The autodoc extension will substitute domain declarations (like above) depending if the object has a docstring and if you are using the :members: and or :undoc-members: options. So you have to verify you are using the correct option and directive for your case.

Your rst file
-------------

.. autoclass:: Your_Module.Your_Class
   :members:

The above example will be substituted by a :py:class:: domain declaration if the corresponding class has a docstring, if not you need to add the :undoc-members: option.

---

---

The symptoms you are describing of having empty indexes happens when you haven't declared anything in the .rst files. With the nuance that the autodoc directives may or may not do those declarations for you depending if the objects have docstrings and you used the right options in the directives.

---

---

EDIT: You should also run make clean before your builds (e.g.make html) because inconsistencies between builds can break the index.

Solution 2:

As I eventually worked out in the comments, thanks to help from @bad_coder, my problem was specific to building the docs in readthedocs.io

Building the docs locally worked fine.

The reason came down to use of sphinx.ext.autodoc, perhaps in conjunction with sphinx_autodoc_typehints, which seems to need to import my actual python code. Checking the logs of my apparently successful readthedocs build showed actually there were warnings like:

WARNING: autodoc: failed to importmodule'whatever'frommodule'myproject'; the following exception was raised:
Nomodule named 'somelib'

i.e the docs had only partially built, it had skipped the parts it couldn't do.

The build worked locally because I was already in a virtualenv with all my project's dependencies installed.

(IMHO this seems like a bad design of the sphinx.ext.autodoc and/or sphinx_autodoc_typehints ...good static-analysis tools exist for Python which can build an AST or CST and extract structure and docstrings without importing any code.)

Well anyway, this meant that I needed to tell readthedocs.io how to install all my project deps. This is slightly complicated by the fact I'm using Poetry, which is not explicitly supported. This means I don't have a requirements.txt file to point to (and I don't want to manually create one that is a duplicate of everything in my pyproject.toml).

Fortunately the pyproject.toml file is understandable by pip, so we're able to use the pip install method described here for readthedocs.io to install both my project deps, plus extra deps that are only needed for building docs: https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-664002569

To summarise:

1. Deleted my docs/requirements.txt
2. Added:

   [tool.poetry.dependencies]
   ...
   sphinx = {version = "^3.1.1", optional = true}
   sphinx-autodoc-typehints ={version = "^1.11.1", optional = true}
   

   and:

   [tool.poetry.extras]docs = [
       "sphinx",
       "sphinx-autodoc-typehints"
   ]
   

   to my pyproject.toml
3. Updated my .readthedocs.yml to:

   version:2sphinx:configuration:docs/conf.pypython:version:3.8install:-method:pippath:.extra_requirements:-docs

4. Pushed these changes to readthedocs.io ...voilà, now it works.