genindex 和 modindex 页脚链接在 readthedocs.io 中不起作用

Question

我有一个使用 Sphinx 的文档的 Python 项目。我正在 readthedocs.io 服务上远程构建文档。

我使用了 sphinx-quickstart，它生成了一个 index.rst 文件，在页脚中包含这些 link：

Indices and tables
~~~~~~~~~~~~~~~~~~

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

当我将更改推送到 readthedocs.io 并构建文档时，我的构建成功了。我通过 toctree 指令手动 link 编辑的文档都可以正常工作。

search link 工作正常。

但是 genindex link 转到一个空白页面，标题为“索引”

和 modindex 页面 link 到 py-modindex.html，这是一个 404。

遵循本指南：https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs 我运行 sphinx-apidoc -o api-docs/ ../myproject 生成了 autodoc .rst 文件。

我 link 在我的 index.rst 顶部的 toctree 部分编辑了结果 api-docs/modules.rst... link 有效，如果我点击通过api-docs已经正确生成

sphinx-autodoc 还为我的项目中的每个包生成了文件，它们包含如下指令：

myproject.whatever module
-------------------------

.. automodule:: myproject.whatever
   :members:
   :undoc-members:
   :show-inheritance:

如果我直接浏览到这些页面，它们有内容，但它们不会出现在索引中（只有手动 link 编辑的目录）。

我也有一些手动创作的页面，也是通过目录 link编辑的。

我的 docs/conf.py 看起来像：

import os
import sys

sys.path.insert(0, os.path.abspath("../"))

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
    "sphinx_autodoc_typehints",
]

templates_path = ["_templates"]

exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

html_theme = "alabaster"

html_static_path = ["_static"]

我相信从 autodoc .rst 存根文件生成的 html 充满了模块并且类从我项目的 .py 文件中提取的事实表明sys 路径修复和 autodoc 基本上可以正常工作。

所以我的问题是：

如何让:ref:`genindex` 有一些内容？
如何修复 :ref:`modindex` 指向不存在的 py-modindex.html？

Answer 1

genindex 和 modindex 由 Sphinx 自动管理。应考虑两种情况：

.rst 文件中的任何声明都将插入到这些索引中。例如，如果您从 Python 域声明 a function：

Your rst file
-------------

.. py:function:: name(parameters)

即使在任何 .py 文件中没有对应的函数，它也会被插入到索引中。

使用 autodoc 指令，同样适用于更多的规则。 autodoc 扩展将替换域声明（如上），具体取决于对象是否具有文档字符串以及您是否使用 :members: 和或 :undoc-members: 选项。因此，您必须验证您使用的是正确的选项和指令。

Your rst file
-------------

.. autoclass:: Your_Module.Your_Class
   :members:

如果相应的 class 有文档字符串，上面的例子将被 :py:class:: 域声明代替，如果没有，则需要添加 :undoc-members: 选项。

当您没有在 .rst 文件中声明任何内容时，就会出现您描述的索引为空的症状。 autodoc 指令可能会或可能不会为您做这些声明的细微差别取决于对象是否有文档字符串以及您在指令中使用了正确的选项。

编辑： 您还应该运行 make clean 在构建之前（例如 make html），因为构建之间的不一致会破坏索引。

Answer 2

由于@bad_coder 的帮助，我最终在评论中解决了问题，我的问题特定于在 readthedocs.io

中构建文档

在本地构建文档工作正常。

原因归结为使用 sphinx.ext.autodoc，可能与 sphinx_autodoc_typehints 结合使用，这似乎需要导入我的实际 python 代码。检查我显然成功的 readthedocs 构建的日志显示实际上有这样的警告：

WARNING: autodoc: failed to import module 'whatever' from module 'myproject'; the following exception was raised:
No module named 'somelib'

即文档只构建了一部分，它跳过了它不能构建的部分。

构建在本地运行，因为我已经在安装了所有项目依赖项的 virtualenv 中。

（恕我直言，这似乎是 sphinx.ext.autodoc and/or sphinx_autodoc_typehints 的糟糕设计 ...Python 存在良好的 static-analysis 工具，可以构建AST 或 CST 并在不导入任何代码的情况下提取结构和文档字符串。）

无论如何，这意味着我需要告诉 readthedocs.io 如何安装我所有的项目部门。由于我使用的是未明确支持的 Poetry，因此这有点复杂。这意味着我没有要指向的 requirements.txt 文件（而且我不想手动创建一个与 pyproject.toml 中的所有内容重复的文件）。

幸运的是 pyproject.toml 文件可以被 pip 理解，所以我们可以使用这里为 readthedocs.io 描述的 pip install 方法来安装我的项目 deps ，加上仅在构建文档时需要的额外部门：https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-664002569

总结一下：

删除了我的docs/requirements.txt

添加：

[tool.poetry.dependencies]
...
sphinx = {version = "^3.1.1", optional = true}
sphinx-autodoc-typehints ={version = "^1.11.1", optional = true}

和：

[tool.poetry.extras]
docs = [
    "sphinx",
    "sphinx-autodoc-typehints"
]

我的 pyproject.toml

将我的 .readthedocs.yml 更新为：

version: 2

sphinx:
  configuration: docs/conf.py

python:
  version: 3.8
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

将这些更改推送到 readthedocs.io ...瞧，现在可以使用了。

genindex 和 modindex 页脚链接在 readthedocs.io 中不起作用

genindex and modindex footer links don't work in readthedocs.io

restructuredtext

python-sphinx

autodoc

read-the-docs