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

问题描述

我有一个使用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顶部的toctree部分中链接了所得的index.rst ...该链接有效，并且如果我单击api-docs，就会生成该链接正确。

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

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

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

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

我还有一些手动创作的页面，再次通过目录链接。

我的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域中声明a function：

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

.. py:function:: name(parameters)

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

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

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

.. autoclass:: Your_Module.Your_Class
   :members:

如果相应的类具有文档字符串，则上面的示例将用:py:class::域声明代替，否则，您需要添加:undoc-members:选项。

当您在.rst文件中未声明任何内容时，就会出现所描述的具有空索引的症状。细微之处在于autodoc指令可能会为您做那些声明，也可能不会为您做这些声明，具体取决于对象是否具有docstrings，并且您在指令中使用了正确的选项。

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

当我最终在注释中得出结论时，由于@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和/或sphinx_autodoc_typehints的错误设计……对于Python而言，存在良好的静态分析工具，该工具可以构建AST或CST并提取结构和文档字符串而无需导入任何代码。）

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

幸运的是，pyproject.toml可以理解pip文件，因此我们可以使用此处描述的pip install方法为readthedocs.io安装我的项目部门和其他部门只需要生成文档即可使用：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 ...voilà，现在可以使用了。

autodoc python-sphinx read-the-docs restructuredtext