使用狮身人面像时,没有生成模块索引“modindex”
问题描述:
我有使用sphinx-build创建文档目录(html)的麻烦。使用狮身人面像时,没有生成模块索引“modindex”
我试图
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
需要描述每个模块的第一个文件。幸运的是,使用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:为了避免额外的警告,在index.rst
文件添加modules
到Contents:
toctree。
你的index.rst文件中是否有“*:ref:'modindex'”?请提供index.rst文件的内容。 – alecxe
您是使用autodoc还是将模块手动添加到modindex?如果使用autodoc,那么你必须[在'conf.py'](http://sphinx-doc.org/tutorial.html#autodoc)的扩展名列表中包含''sphinx.ext.autodoc''。如果手动,然后使用['..py:module:'''''''''''''''''''''''''''''''''''''''''''你想在索引中列出每个模块的指令](http://sphinx-doc.org/domains.html#directive-py:module)。检查构建错误re:角色和指令,因为如果出现错误,modindex不会生成。起初我有同样的问题,但检查错误修复了它。 –
我面临与Karin相同的问题,其中autodoc的设置跟随Mark的检查点。但是,它还没有生成monindex.html。我错过了任何一步? –