genindex 和 modindex 页脚链接在 readthedocs.io 中不起作用 [英] genindex and modindex footer links don't work in readthedocs.io

问题描述

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

I have a Python project using Sphinx for docs. I am building the docs remotely on readthedocs.io service.

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

I used sphinx-quickstart and it generated an index.rst file with these links in the footer:

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

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

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

When I push changes to readthedocs.io and build the docs, my build succeeds. Docs that I manually linked via toctree directive all work fine.

search 链接工作正常.

但是 genindex 链接转到一个空白页面，标题为Index"

But the genindex link goes to an empty page, titled "Index"

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

And the modindex page links to py-modindex.html, which is a 404.

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

Following this guide: https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs I had run sphinx-apidoc -o api-docs/ ../myproject to generate the autodoc .rst files.

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

I linked the resulting api-docs/modules.rst in the toctree section at the top of my index.rst... That link works and if I click through the api-docs have been generated correctly.

同样由 sphinx-autodoc 生成的是我项目中每个包的文件，它们包含如下指令:

Also generated by sphinx-autodoc were files for each package in my project, they contain directives like:

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

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

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

If I browse directly to these pages they have content, but they don't appear in the index (only the tocs they are manually linked in).

我也有一些手动创作的页面，同样通过 toc 链接.

I also have some manually authored pages, again linked via 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路径修复和自动文档基本上都在工作.

I believe the fact that html generated from the autodoc .rst stub files are filled with modules and classes extracted from the .py files in my project indicates that the sys path fix and autodoc are basically working.

所以我的问题是:

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

• How to make :ref:`genindex` have some content?
• How to fix :ref:`modindex` points to py-modindex.html which does not exist?

推荐答案

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

As I eventually worked out in the comments, thanks to help from @bad_coder, my problem was specific to building the docs in readthedocs.io

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

Building the docs locally worked fine.

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

The reason came down to use of sphinx.ext.autodoc, perhaps in conjunction with sphinx_autodoc_typehints, which seems to need to import my actual python code. Checking the logs of my apparently successful readthedocs build showed actually there were warnings like:

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

即文档只是部分构建，它跳过了它不能做的部分.

i.e the docs had only partially built, it had skipped the parts it couldn't do.

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

The build worked locally because I was already in a virtualenv with all my project's dependencies installed.

(恕我直言，这似乎是 sphinx.ext.autodoc 和/或 sphinx_autodoc_typehints 的糟糕设计......对于 Python 来说，存在良好的静态分析工具，它可以构建AST 或 CST 并在不导入任何代码的情况下提取结构和文档字符串.)

(IMHO this seems like a bad design of the sphinx.ext.autodoc and/or sphinx_autodoc_typehints ...good static-analysis tools exist for Python which can build an AST or CST and extract structure and docstrings without importing any code.)

无论如何，这意味着我需要告诉 readthedocs.io 如何安装我所有的项目 deps.由于我使用的是没有明确支持的 Poetry，这有点复杂.这意味着我没有要指向的 requirements.txt 文件(并且我不想手动创建一个与我的 pyproject.toml).

Well anyway, this meant that I needed to tell readthedocs.io how to install all my project deps. This is slightly complicated by the fact I'm using Poetry, which is not explicitly supported. This means I don't have a requirements.txt file to point to (and I don't want to manually create one that is a duplicate of everything in my pyproject.toml).

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

Fortunately the pyproject.toml file is understandable by pip, so we're able to use the pip install method described here for readthedocs.io to install both my project deps, plus extra deps that are only needed for building docs: https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-664002569

总结:

1. 删除了我的docs/requirements.txt
2. 补充:

1. Deleted my docs/requirements.txt
2. Added:

[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 中不起作用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！