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

Question

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

我使用了sphinx-quickstart，它生成了一个index.rst 文件，页脚中有这些链接：

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

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

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

search 链接可以正常工作。

但是genindex 链接指向一个空白页面，标题为“索引”

而modindex 页面链接到py-modindex.html，这是一个404。

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

我将生成的api-docs/modules.rst 链接到我的index.rst 顶部的toctree 部分...该链接有效，如果我点击api-docs，则已正确生成。

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

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

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

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

我还有一些手动创建的页面，再次通过 toc 链接。

我的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 自动管理。应该考虑两种情况：

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

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

.. py:function:: name(parameters)

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

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

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

.. autoclass:: Your_Module.Your_Class
   :members:

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

---

---

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

---

---

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

Answer 2

感谢@bad_coder 的帮助，我最终在 cmets 中锻炼，我的问题是在 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 和/或 sphinx_autodoc_typehints 的糟糕设计……Python 存在良好的静态分析工具，它可以构建 AST 或 CST 并在不导入任何代码的情况下提取结构和文档字符串。 )

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

幸运的是，pip 可以理解 pyproject.toml 文件，因此我们可以使用这里描述的用于 readthedocs.io 的 pip install 方法来安装我的两个项目 deps，以及仅用于构建的额外 deps文档：https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-664002569

总结一下：

1. 删除了我的docs/requirements.txt
2. 添加：

   [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
3. 将我的.readthedocs.yml 更新为：

   version: 2
   
   sphinx:
     configuration: docs/conf.py
   
   python:
     version: 3.8
     install:
       - method: pip
         path: .
         extra_requirements:
           - docs
   

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