我在使用 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 . mymoduleconf.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但是取消注释并更改以in开头的行可以conf.py解决问题。
我的是：sys.path.insert(0, os.path.abspath('mymodule'))
PS：为避免额外的警告，请添加modules到文件Contents:中的目录树中index.rst。
以下是我为我的项目所做的。
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
老问题，但“在硬盘上工作而不是在 ReadTheDocs 上工作”通常很容易解决。