问题描述
我有一个使用 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 topy-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
总结:
- 删除了我的
docs/requirements.txt
- 补充:
- Deleted my
docs/requirements.txt
- 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
这篇关于genindex 和 modindex 页脚链接在 readthedocs.io 中不起作用的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持!