No generation of the module index “modindex” when using Sphinx

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.

Leave a Comment

Hata!: SQLSTATE[HY000] [1045] Access denied for user 'divattrend_liink'@'localhost' (using password: YES)