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.

Answer 1

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.