当依赖项需要身份验证时，Readthedocs 构建忽略子模块（例如：当 python 包需要 Google Earth Engine 时）

Question

我的软件包有 Google Earth Engine 的 Python API（软件包名称：ee）作为依赖项。使用 sphinx 到 auto-generate 文档（用于最终存储在 readthedocs 上）在本地工作，但是所有导入 ee 的子模块都不构建在 readthedocs.com 上。构建日志中的错误消息表明这是因为ee需要身份验证，而readthedocs无法对其进行身份验证。

问题：有没有办法为 readthedocs 保存我自己的身份验证令牌，以便我的文档可以为我的所有子模块正确构建？例如在我的 setup.py 文件或 readthedocs.yaml 或 environment.yaml 文件中？或者是否有另一种解决方法来托管我本地构建的文档而无需 readthedocs 尝试运行代码本身？

总结：

期望的行为：所有子模块自动显示它们的功能和文档。

实际行为：只有不导入 ee 的模块（目前 waterpyk.calcs）在文档中有信息，其余的只有标题是空白的。我相信这是因为 ee 需要身份验证。

再现性：

GitHub 回购：https://github.com/erica-mccormick/waterpyk

Readthedocs 网页：https://waterpyk.readthedocs.io/en/latest/

Readthedocs 原始构建：https://readthedocs.org/api/v2/build/17058090.txt

有关 ee 身份验证的更多信息，请参阅此处有关 ee python 安装的信息：https://developers.google.com/earth-engine/guides/python_install。我正在使用 conda 进行包管理。

这是错误示例（在此之后继续，重复。请参阅上面的原始 link）：

WARNING: autodoc: failed to import module 'main' from module 'waterpyk'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/data.py", line 223, in get_persistent_credentials
    return Credentials(None, **oauth.get_credentials_arguments())
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/oauth.py", line 72, in get_credentials_arguments
    with open(get_credentials_path()) as creds:
FileNotFoundError: [Errno 2] No such file or directory: '/home/docs/.config/earthengine/credentials'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/sphinx/ext/autodoc/importer.py", line 70, in import_module
    return importlib.import_module(modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
  File "<frozen importlib._bootstrap>", line 991, in _find_and_load
  File "<frozen importlib._bootstrap>", line 975, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 671, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 843, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/checkouts/latest/waterpyk/main.py", line 4, in <module>
    ee.Initialize()
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/__init__.py", line 122, in Initialize
    credentials = data.get_persistent_credentials()
  File "/home/docs/checkouts/readthedocs.org/user_builds/waterpyk/conda/latest/lib/python3.8/site-packages/ee/data.py", line 225, in get_persistent_credentials
    raise ee_exception.EEException(
ee.ee_exception.EEException: Please authorize access to your Earth Engine account by running

earthengine authenticate

in your command line, and then retry.

Answer 1

这是 autodoc_mock_imports 选项的一个用例，它在“构建时未满足某些外部依赖项并中断构建过程”时非常方便。

在 conf.py 中添加以下行即可解决问题：

autodoc_mock_imports = ["ee"]

当依赖项需要身份验证时，Readthedocs 构建忽略子模块（例如：当 python 包需要 Google Earth Engine 时）

Readthedocs build ignores submodules when dependency requires authentication (ex: when python package requires Google Earth Engine)

python

google-authentication

python-sphinx

read-the-docs

google-earth-engine