文档字符串不包括在Read the Docs Sphinx版本中

问题描述

我构建了一个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

我做错了什么？

---

解决方案

请记住，Sphinx的Autodoc扩展导入了要记录的模块。这是因为AutoDoc使用了Python自检来访问文档字符串。从AutoDoc的角度来看，这有一个优势，那就是它可以让Python进行解析。从用户的角度来看，缺点是我们必须确保安装了所有依赖项，或者至少"；mocked"；。

在您的开发机器上这不是问题，因为您的包所依赖的所有外部库都已经安装好了。但是，当在Read-the-Docs服务器上构建时，在所谓的裸露的Python环境中，它们中的许多都缺失了。您向docs/requirements.txt添加了构建Sphinx项目所需的依赖项，如果您没有使用AutoDoc扩展，这就足够了。但既然这样做了，您的文档字符串就会丢失，因为包中的模块会导入类似flask_login或plotly的内容。在Read-the-Docs中，如果您查看扩展日志(不是您发布的基本日志)，应该会看到类似的警告消息，您可以通过单击Builds选项卡中的查看原始日志来访问该日志。这些是警告，而不是错误。因此生成通过，但缺少文档字符串。

添加额外的依赖项将减慢文档构建的速度，因为它们都必须在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()