Python sphinx genindex和modindex页脚链接不'；我不能在readthedocs.io中工作

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

我使用了

sphinx quickstart

，它生成了一个

index.rst

文件，页脚中有以下链接：

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

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

当我将更改推送到readthedocs.io并构建文档时，构建成功。我通过

目录树

指令手动链接的文档都可以正常工作

搜索

链接工作正常

但是

genindex

链接指向一个名为“Index”的空页面

而

modindex

页面链接到

py modindex.html

，这是一个404

遵循本指南：我已经运行了

sphinxapidoc-oapidocs/./myproject

来生成autodoc.rst文件

我在

索引.rst

顶部的

目录树

部分链接了生成的

api文档/modules.rst

。。。该链接起作用，如果我点击

api，文档

已正确生成

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 path fix和autodoc基本上正常工作

所以我的问题是：

• 如何使

  ：ref:`genindex`

  有一些内容
• 如何修复

  ：ref:`modindex`

  指向不存在的

  py modindex.html

---

genindex

和

modindex

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

.rst

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

即使它在任何

.py

文件中没有相应的函数，它也会被插入索引中

使用autodoc指令，这同样适用于其他一些规则。autodoc扩展将替换域声明（如上所述），具体取决于对象是否具有docstring，以及您是否正在使用

：members:

和或

：undoc members:

选项。因此，您必须验证您是否针对您的案例使用了正确的选项和指令

如果对应的类有docstring，则上面的示例将被一个

：py:class:

域声明替换，如果没有，则需要添加

：undoc members:

选项

---

---

当您没有在

.rst

文件中声明任何内容时，就会出现您描述的索引为空的症状。不同的是，autodoc指令可能会也可能不会为您执行这些声明，这取决于对象是否具有docstring，以及您是否在指令中使用了正确的选项

---

---

---

编辑：您还应该在构建之前运行

make clean

（例如

make html

），因为构建之间的不一致会破坏索引。

genindex

和

modindex

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

.rst

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

即使它在任何

.py

文件中没有相应的函数，它也会被插入索引中

使用autodoc指令，这同样适用于其他一些规则。autodoc扩展将替换域声明（如上所述），具体取决于对象是否具有docstring，以及您是否正在使用

：members:

和或

：undoc members:

选项。因此，您必须验证您是否针对您的案例使用了正确的选项和指令

如果对应的类有docstring，则上面的示例将被一个

：py:class:

域声明替换，如果没有，则需要添加

：undoc members:

选项

---

---

当您没有在

.rst

文件中声明任何内容时，就会出现您描述的索引为空的症状。不同的是，autodoc指令可能会也可能不会为您执行这些声明，这取决于对象是否具有docstring，以及您是否在指令中使用了正确的选项

---

---

---

编辑：您还应该在构建之前运行

make clean

（例如

make html

），因为构建之间的不一致会破坏索引。

由于@bad\u coder的帮助，我最终在评论中得出结论，我的问题是在readthedocs.io中构建文档

在本地构建文档效果良好

原因在于使用了

sphinx.ext.autodoc

，可能与

sphinx\u autodoc\u typehints

结合使用，这似乎需要导入我的实际python代码。检查我显然成功的readthedocs构建的日志显示，实际上存在如下警告：

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

i、 e文档只构建了一部分，它跳过了无法完成的部分

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

（依我看，

sphinx.ext.autodoc

和/或

sphinx\u autodoc\u typehits

的设计似乎很糟糕……Python有很好的静态分析工具，可以构建AST或CST，并在不导入任何代码的情况下提取结构和文档字符串。）

不管怎样，这意味着我需要告诉readthedocs.io如何安装我所有的项目DEP。这有点复杂，因为我使用的是诗歌，这不是明确的

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

.. autoclass:: Your_Module.Your_Class
   :members:

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

[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"
]