文档字符串不包含在阅读文档 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

也许您需要在 conf.py.

中扩展您的来源路径

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

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

如果您添加 conf.py

会更容易帮助您

Answer 2

请记住，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']

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

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

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

Docstrings are not included in Read the Docs Sphinx build

python

python-sphinx

read-the-docs

autodoc