43

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

4

3 回答 3

40

精简版

  • 跑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但是取消注释并更改以in开头的行可以conf.py解决问题。

我的是：sys.path.insert(0, os.path.abspath('mymodule'))

PS：为避免额外的警告，请添加modules到文件Contents:中的目录树中index.rst。

于 2015-03-30T22:55:06.660 回答
0

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

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
于 2022-02-01T20:37:41.150 回答
-5

老问题，但“在硬盘上工作而不是在 ReadTheDocs 上工作”通常很容易解决。

  • 去阅读文档
  • 导航到您的“项目主页”
  • 点击“管理员”，然后点击“高级设置”
  • 找到并选中“安装项目”复选框
  • 返回“概览”
  • 构建一个新版本
  • 检查它是否有效
  • 回来谢谢我
于 2019-10-30T16:21:15.330 回答