短版

Question

使用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。

Answer 1

短版

运行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需要描述每个模块的第一个文件。幸运的是，使用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 toctree。

Answer 2

古老的问题，但是“在硬盘驱动器上工作而不在ReadTheDocs上工作”通常可以轻松解决。

去阅读文档
导航到“项目主页”
点击“管理员”，然后点击“高级设置”
找到并选中“安装项目”框
返回“概述”
构建新版本
检查是否有效
回到这里谢谢我

使用Sphinx时，不生成模块索引“modindex”

2 个答案:

短版

长答案