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.

Do you have "* :ref:`modindex`" in your index.rst file? Please, provide the contents of index.rst file. — alecxe, Jan 30 '13 at 11:21
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`](http://sphinx-doc.org/tutorial.html#autodoc). If manual, then use the [`.. py:module: ` directive for each module that you want listed in the index](http://sphinx-doc.org/domains.html#directive-py:module). 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. — Mark Mikofski, Apr 25 '13 at 20:26
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? — 吳強福, Jan 29 '14 at 06:53

score 44 · Answer 1 · answered Mar 30 '15 at 22:55

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.

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, Oct 01 '19 at 08:33
Mistake also highlighted here: https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/ — visoft, Oct 01 '19 at 08:34

score 3 · Answer 2 · edited Feb 01 '22 at 20:43

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

score -6 · Answer 3 · answered Oct 30 '19 at 16:21

Old question, but "working on the hard drive but not on ReadTheDocs" often has an easy fix.

Go to readthedocs
Navigate to your "Project Home"
Click 'Admin' then 'Advanced Settings'
Find and check the box for 'Install Project'
Return to 'Overview'
Build a new version
Check if it worked
Come back here and thank me

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

3 Answers3

Short version

Long answer