No generation of the module index "modindex" when using Sphinx

Question

I have troubles creating a document directory (html) using sphinx-build.

I tried

sphinx-build -b html source build

as well as

make html

but in both cases only the html-files search.html, index.html and genindex.html are generated. The file modindex.html is missing.

In the file conf.py I set

html_domain_indices = True

so I should have a modindex.html file. What am I doing wrong? I get no error message after building the html files. I'm using Sphinx 1.1.3 and Python 2.7 on Windows XP.

Solution

Short version

• run sphinx-apidoc -o . mymodule
• uncomment and modify conf.py. For this example, sys.path.insert(0, os.path.abspath('mymodule'))
• re-run make html

Long answer

I can reproduce the issue with this sample module:

$cat mymodule/mymodule.py
def fn1():
    '''First function'''
    pass

def fn2():
    '''Second function'''
    pass

Running sphinx-quickstart produces the following tree:

$tree
.
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── mymodule
    └── mymodule.py

$cat index.rst
.. sphinx example documentation master file, created by
   sphinx-quickstart on Mon Mar 30 15:28:37 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

with default index.rst:

Welcome to sphinx example's documentation!
==========================================

Contents:

.. toctree::
   :maxdepth: 2



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Running make html at this point produces no output in _build/html/py-modindex.html. This is because sphinx needs .rst files describing every module. Fortunately it's easy to produce using sphinx-apidoc -o . mymodule. This gives two new files, of which only mymodule.rst is necessary to fix the modindex issue in the question.

$head *mod*rst
==> modules.rst <==
mymodule
========

.. toctree::
   :maxdepth: 4

   mymodule

==> mymodule.rst <==
mymodule module
===============

.. automodule:: mymodule
    :members:
    :undoc-members:
    :show-inheritance:

Running make html at this point still won't work. But uncommenting and changing the line beginning with sys.path.insert in conf.py fixes things.

Mine is: sys.path.insert(0, os.path.abspath('mymodule'))

PS: to avoid an additional warning, add modules to the Contents: toctree in the index.rst file.

Comments

[alecxe]

Do you have "* :ref:modindex" in your index.rst file? Please, provide the contents of index.rst file.

[Mark Mikofski]

Are you using autodoc, or are you adding modules to the modindex manually? If using autodoc then you must include 'sphinx.ext.autodoc' in the list of extensions in conf.py. If manual, then use the .. py:module: <name> directive for each module that you want listed in the index. Check the build for errors re: roles and directives, as modindex will not build if there are errors. I had this same issue at first, but checking for errors fixed it.

[吳強福]

I face the same problem as Karin, where the setting of autodoc followed the checkpoints from Mark. However, it is still no monindex.html generated. Did I miss any step?

[visoft]

Another mistake (that I did) is not specifying correctly the output folder for sphinx-apidoc. In my case the documentation sources live in docs/source folder. Of course the apidoc command was run from docs/. Once all above conditions were met (proper inclusion of the modules, proper output) it worked!

[visoft]

Mistake also highlighted here: samnicholls.net/2016/06/15/how-to-sphinx-readthedocs