Read the Docs Sphinx build 中不包含文档字符串

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 上，如果您查看扩展日志（不是您发布的基本日志），您应该会看到与此相关的警告消息，可以通过单击“构建”选项卡中的“查看原始日志”来访问该日志。这些是警告，而不是错误。所以构建通过了，但是缺少文档字符串。

添加额外的依赖项会减慢文档构建速度，因为它们都必须在 Sphinx 开始工作之前安装。所以更好的策略是嘲笑他们。你可以先在本地测试，在一个新的虚拟环境中。

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

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 会更容易帮助你