使用Sphinx时,不生成模块索引"modindex"

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需要.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:toctree index.rst.

Answer 2

以下是我为我的项目所做的事情。

1.安装狮身人面像

   pip install -U sphinx

2.安装主题（我选择了sphinx_rtd_theme。请用你的选择替换它）

   pip install sphinx sphinx_rtd_theme

3.在你的项目文件下创建一个doc目录

   mkdir docs

4.进入该目录

   cd docs

5.运行sphinx-quickstart命令

   sphinx-quickstart 

6. 运行以下命令（如果您已启用 autodoc shpinx 扩展）

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

其中source是 sphinx 使用的源文件夹，modules_folder是项目的 .py 文件模块所在的文件夹。

7.系统将提示您回答以下问题（根据您的需要更改答案）

   > 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.如果运行成功，应该如下所示：

   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. 编辑conf.py并确保以下行没有注释（#）：

   import os               # line 13
   import sys              # line 14

注意： .. 代表 doc 目录之上的一个目录 <modules_folder> 是项目的 .py 文件模块所在的文件夹

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

确保以下行存在

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

如果您愿意，可以更改主题

   html_theme = 'sphinx_rtd_theme'                                      # line 51

10.运行shpinx-apidoc命令

   sphinx-apidoc -o . ..

笔记： 。>> 表示当前目录 ..>> 表示上一级目录，即 <modules_folder> 项目目录

11.运行make html命令

  .\make clean
  .\make HTML

or

   make clean
   make html

12. 打开您新建的网页，从

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