文档字符串不包含在阅读文档 Sphinx 构建中

Question

我构建了一个 Sphinx 文档并且构建在本地运行良好。我的文档字符串如下所示。

迁移到 readthedoc.io 时，我在 docs/requirement.txt 下添加了一个特定的需求文件，即：

sphinx==3.5.4
sphinx_rtd_theme==0.5.2
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4

我的 .readthedocs.yaml 看起来像：

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/source/conf.py

# Optionally build your docs in additional formats such as PDF
formats:
   - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
   version: 3.7
   install:
    - requirements: docs/requirements.txt

但是，在 readthedocs.io 上构建文档时，即使我的构建完成且没有错误，文档字符串也不会显示。

这是日志：

git clone --no-single-branch --depth 50 https://github.com/Green-Investement-Dashboard/GRID_app.git .
git checkout --force origin/app_v2
git clean -d -f -f
python3.7 -mvirtualenv /home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --upgrade --no-cache-dir pip setuptools
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --upgrade --no-cache-dir mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme readthedocs-sphinx-ext<2.2
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m pip install --exists-action=w --no-cache-dir -r docs/requirements.txt
cat docs/source/conf.py
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
/home/docs/checkouts/readthedocs.org/user_builds/grid-app/envs/latest/bin/python -m sphinx -b latex -D language=en -d _build/doctrees . _build/latex
cat latexmkrc
latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=grid-app -interaction=nonstopmode
mv -f /home/docs/checkouts/readthedocs.org/user_builds/grid-app/checkouts/latest/docs/source/_build/latex/grid-app.pdf /home/docs/checkouts/readthedocs.org/user_builds/grid-app/artifacts/latest/sphinx_pdf/grid-app.pdf

我做错了什么？

Answer 1

请记住，Sphinx 的 Autodoc 扩展“导入要记录的模块”。这是因为 Autodoc 使用 Python 自省来访问文档字符串。从 Autodoc 的角度来看，这样做的好处是它可以让 Python 进行解析。从用户的角度来看，缺点是我们必须确保安装了所有依赖项，或者至少“模拟”了所有依赖项。

这在您的开发机器上不是问题，您的包所依赖的所有外部库自然都已安装。但是当在 Read-the-Docs 服务器上构建时，可以说是在“裸”的 Python 环境中，其中许多都丢失了。您将构建 Sphinx 项目所需的依赖项添加到 docs/requirements.txt，如果您不使用 Autodoc 扩展就足够了。但是既然你这样做了，你的文档字符串就会丢失，因为包中的模块导入了类似 flask_login 或 plotly 的东西。在 Read-the-Docs 上，如果您查看扩展日志（不是您发布的基本日志），您应该会看到该效果的警告消息，可以通过单击 Builds 选项卡中的“View raw”访问该日志。这些是警告，而不是错误。所以构建通过了，但缺少文档字符串。

添加额外的依赖会减慢文档构建的速度，因为它们都必须在 Sphinx 开始工作之前安装。所以更好的策略是嘲笑他们。您也可以在本地进行测试。

像 import numpy 这样导入的包可以通过添加 Autodoc 选项 autodoc_mock_imports 到 conf.py 来模拟：

autodoc_mock_imports = ['numpy']

如果您直接从包的命名空间导入对象，例如 from numpy import array，则可能需要使用 unittest 模块中的 MagicMock 来代替：

from unittest.mock import MagicMock
sys.modules['numpy'] = MagicMock()

Answer 2

也许您需要将路径扩展到 conf.py 中的源代码。

例如像这样（如果您的文档在子目录中）：

sys.path.insert(0, os.path.abspath("../"))

如果你添加你的 conf.py 会更容易帮助你