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.

Answer 2

The following is what I did for my project.

1. Install sphinx

   pip install -U sphinx

2. Install theme (I've chosen sphinx_rtd_theme. Pleaser replace it with your choice)

   pip install sphinx sphinx_rtd_theme

3. Create a doc directory under your project file

   mkdir docs

4. Get into that directory

   cd docs

5. Run sphinx-quickstart command

   sphinx-quickstart 

6. Run the following ( if you've enabled autodoc shpinx extension)

  sphinx-apidoc -o source/ ../<modules_folder>

where source is the source folder used by sphinx and modules_folder is the folder your project's .py files-modules are in.

7. You will be prompted to reply to the questions below (change the answers according to your needs)

   > Separate source and build directories (y/n) [n]: y
   The project name will occur in several places in the built documentation.
   > Project name: project_name
   > Author name(s): your_nme
   > Project release []: 1.01
   > Project language [en]: en

8. It should look like the following if successfully run:

   Creating file ...<***modules_folder***>/docs/source/conf.py.
   Creating file ...<***modules_folder***>/docs/source/index.rst.
   Creating file ...<***modules_folder***>/docs/Makefile.
   Creating file ...<***modules_folder***>/docs/make.bat.

   Finished: An initial directory structure has been created.

9. Edit conf.py and make sure the following lines are not commented (#):

   import os               # line 13
   import sys              # line 14

Note: .. stands for one directory up from doc directory <modules_folder> is the folder your project's .py files-modules are in

   sys.path.insert(0, os.path.abspath('../<modules_folder>/'))          # line 16

make sure the following line exists

   extensions = ['sphinx.ext.autodoc']                                  # line 34

change the theme if you'd like

   html_theme = 'sphinx_rtd_theme'                                      # line 51

10. Run shpinx-apidoc command

   sphinx-apidoc -o . ..

Note: . >> is for current directory ..>> is for one level up directory, i.e., the <modules_folder> project directory

11. Run make html command

  .\make clean
  .\make HTML

or

   make clean
   make html

12. Open your newely built webpage starting with

  <modules_folder>/docs/build/html/index.html