python-sphinx之使用 Sphinx 时不生成模块索引 "modindex"_编程设计

我在使用 sphinx-build 创建文档目录 (html) 时遇到了麻烦。

我试过

sphinx-build -b html source build

也

make html

但在这两种情况下，只会生成 html 文件 search.html、index.html 和 genindex.html。文件 modindex.html 丢失。

在我设置的文件 conf.py

html_domain_indices = True

所以我应该有一个 modindex.html 文件。我究竟做错了什么？构建 html 文件后，我没有收到任何错误消息。我在 Windows XP 上使用 Sphinx 1.1.3 和 Python 2.7。

请您参考如下方法:

简洁版本

运行 sphinx-apidoc -o . mymodule

取消注释和修改conf.py .对于此示例，sys.path.insert(0, os.path.abspath('mymodule'))

重新运行make html

长答案

我可以使用此示例模块重现该问题:

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

运行 sphinx-quickstart产生以下树:

$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.

默认 index.rst :

Welcome to sphinx example's documentation! 
========================================== 
 
Contents: 
 
.. toctree:: 
   :maxdepth: 2 
 
 
 
Indices and tables 
================== 
 
* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search`

运行 make html此时在 _build/html/py-modindex.html 中没有输出.这是因为 sphinx需要描述每个模块的 .rst 文件。幸运的是，使用 sphinx-apidoc -o . mymodule 很容易生成.
这给出了两个新文件，其中只有 mymodule.rst有必要解决问题中的 modindex 问题。

$head *mod*rst 
==> modules.rst <== 
mymodule 
======== 
 
.. toctree:: 
   :maxdepth: 4 
 
   mymodule 
 
==> mymodule.rst <== 
mymodule module 
=============== 
 
.. automodule:: mymodule 
    :members: 
    :undoc-members: 
    :show-inheritance:

运行 make html在这一点上仍然行不通。但是取消注释并更改以 sys.path.insert 开头的行在 conf.py解决问题。

我的是: sys.path.insert(0, os.path.abspath('mymodule'))
PS:为避免额外的警告，请添加 modules到 Contents: index.rst 中的目录树文件。