我有一个Python项目，使用Sphinx作为文档。我正在readthedocs.io服务上远程构建文档。
我使用了sphinx-quickstart，它生成了一个index.rst文件，页脚中有以下链接：
Indices and tables
~~~~~~~~~~~~~~~~~~
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
当我推送更改以读取docs.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文件。
我在index.rst顶部的toctree部分中链接了生成的api-docs/modules.rst。。。这个链接是有效的，如果我点击api-docs已经正确生成。
sphinx-autodoc还生成了我项目中每个包的文件，它们包含如下指令：
myproject.whatever module
-------------------------
.. automodule:: myproject.whatever
:members:
:undoc-members:
:show-inheritance:
如果我直接浏览到这些页面，它们有内容，但不会出现在索引中(只有手动链接的toc)。
我也有一些手动编写的页面，再次通过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
genindex和modindex由Sphinx自动管理。应考虑两种情况：
.rst文件中的任何声明都将插入这些索引中。例如，如果您从Python域中声明一个函数：
Your rst file
-------------
.. py:function:: name(parameters)
即使它在任何.py文件中都没有相应的函数，它也会被插入索引中。
- 使用autodoc指令，这同样适用于其他一些规则。autodoc扩展将替换域声明(如上所述)，具体取决于对象是否具有docstring以及是否使用
:members:和/或:undoc-members:选项。因此，您必须验证您是否为您的案例使用了正确的选项和指令
Your rst file
-------------
.. autoclass:: Your_Module.Your_Class
:members:
如果相应的类具有docstring，则上面的示例将被:py:class::域声明所取代，如果不需要添加:undoc-members:选项。
当您没有在.rst文件中声明任何内容时，就会出现您所描述的索引为空的症状。注意，autodoc指令可能为您做这些声明，也可能不为您做，这取决于对象是否有文档字符串，以及您是否在指令中使用了正确的选项。
编辑：您还应该在构建之前运行make clean(例如make html)，因为构建之间的不一致可能会破坏索引。
由于@bad_code的帮助，我最终在评论中解决了问题，我的问题是在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'
即文档只构建了一部分，它跳过了无法完成的部分。
构建在本地工作，因为我已经安装了项目的所有依赖项。
(IMHO，这似乎是sphinx.ext.autodoc和/或sphinx_autodoc_typehints的糟糕设计……Python有很好的静态分析工具，可以在不导入任何代码的情况下构建AST或CST并提取结构和文档字符串。)
无论如何，这意味着我需要告诉readthedocs.io如何安装我所有的项目dep。这有点复杂，因为我使用的是Poetry，它没有得到明确的支持。这意味着我没有一个requirements.txt文件可以指向(而且我不想手动创建一个与pyproject.toml中的所有内容重复的文件)。
幸运的是，pip可以理解pyproject.toml文件，因此我们可以使用此处描述的用于读取docs.io的pip install方法来安装我的两个项目dep，以及仅用于构建文档所需的额外dep：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 - 把这些变化推到读docs.io…瞧，现在它起作用了