当我尝试模拟Sphinx / ReadTheDocs时，它仍然尝试构建模块

Question

我正在尝试使用ReadTheDocs上的Sphinx为a project构建文档，它依赖于一堆pydata包，其中一些依赖于ReadTheDocs上没有的C库(即python-snappy包，它提供了snappy模块，实现了Google的snappy压缩算法，我们在Apache Parquet文件中使用它)。

文档suggests that the solution模拟那些python模块，以便autodoc可以导入它们，即使代码并不在那里，使用conf.py中的autodoc_mock_imports参数，所以我得到了

autodoc_mock_imports = ['snappy', 'python-snappy']

在我的Sphinx conf.py中(我认为它真的应该只是snappy，但我不是100%确定的，一开始它不能与snappy一起工作，所以我添加了包名和模块名……它仍然不起作用)。

但是，文档构建仍在尝试编译snappy，并且可能会失败，因为C语言头文件不可用。当构建收集需求时，它会在项目setup.py中找到python-snappy，并说：

Collecting python-snappy (from pudl==0.1.dev398+g5e075d4)

随后构建失败：

Building wheels for collected packages: pudl, python-snappy
  Building wheel for pudl (setup.py): started
  Building wheel for pudl (setup.py): finished with status 'done'
  Stored in directory: /home/docs/checkouts/readthedocs.org/user_builds/catalyst-cooperative-pudl/.cache/pip/wheels/a4/5f/b6/1f8213aeb5876af1c140b54dce3466b845d989ca1101da875a
  Building wheel for python-snappy (setup.py): started
  Building wheel for python-snappy (setup.py): finished with status 'error'
  ERROR: Complete output from command /home/docs/checkouts/readthedocs.org/user_builds/catalyst-cooperative-pudl/envs/python-packaging/bin/python -u -c 'import setuptools, tokenize;__file__='"'"'/tmp/pip-install-z6c1cop3/python-snappy/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' bdist_wheel -d /tmp/pip-wheel-r54uwk2d --python-tag cp37:
  ERROR: running bdist_wheel
  running build
  running build_py
  creating build
  creating build/lib.linux-x86_64-3.7
  creating build/lib.linux-x86_64-3.7/snappy
  copying snappy/__init__.py -> build/lib.linux-x86_64-3.7/snappy
  copying snappy/snappy_cffi_builder.py -> build/lib.linux-x86_64-3.7/snappy
  copying snappy/__main__.py -> build/lib.linux-x86_64-3.7/snappy
  copying snappy/hadoop_snappy.py -> build/lib.linux-x86_64-3.7/snappy
  copying snappy/snappy_formats.py -> build/lib.linux-x86_64-3.7/snappy
  copying snappy/snappy.py -> build/lib.linux-x86_64-3.7/snappy
  copying snappy/snappy_cffi.py -> build/lib.linux-x86_64-3.7/snappy
  running build_ext
  building 'snappy._snappy' extension
  creating build/temp.linux-x86_64-3.7
  creating build/temp.linux-x86_64-3.7/snappy
  gcc -pthread -Wno-unused-result -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -fPIC -I/home/docs/.pyenv/versions/3.7.3/include/python3.7m -c snappy/snappymodule.cc -o build/temp.linux-x86_64-3.7/snappy/snappymodule.o
  snappy/snappymodule.cc:31:10: fatal error: snappy-c.h: No such file or directory
   #include <snappy-c.h>
            ^~~~~~~~~~~~
  compilation terminated.
  error: command 'gcc' failed with exit status 1
  ----------------------------------------
  ERROR: Failed building wheel for python-snappy
  Running setup.py clean for python-snappy
Successfully built pudl
Failed to build python-snappy

python-snappy在文档构建中包含的requirements.txt中被注释掉了，但当然它仍然包含在项目setup.py的install_requires参数中。

为什么模拟不起作用？我如何让它停止尝试构建这个不能成功的包？在我的本地系统(安装了libsnappy-dev`包)上，文档构建似乎工作得很好。

失败构建的完整输出可以在这里找到：

https://readthedocs.org/projects/catalyst-cooperative-pudl/builds/9376117/

Answer 1

这里的问题是，我还在.readthedocs.yml配置文件中显式地告诉Read The Docs使用pip构建和安装我的pudl包：

# Set the version of Python and requirements required to build your docs
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .
  system_packages: true

这意味着它试图通过运行在存储库顶层找到的setup.py来创建pudl发行版，但由于缺少snappy C头文件，这可能会失败。

解决方案是根据python-snappy环境变量，从setup.py中的install_requires参数中有条件地排除READTHEDOCS包，让被模拟的模块按照autodoc_mock_imports在conf.py中的指定来满足依赖关系

install_requires = [
    'coloredlogs',
    'datapackage',
    'dbfread',
    'goodtables',
    'jupyter',
    'jupyterlab',
    'matplotlib',
    'nbval',
    'networkx>=2.2',
    'numpy',
    'pandas>=0.24',
    'psycopg2',
    'pyarrow>=0.14.0',
    'pyyaml',
    'scikit-learn>=0.20',
    'scipy',
    'sqlalchemy>=1.3',
    'sqlalchemy-postgres-copy',
    'tableschema',
    'timezonefinder',
    'xlsxwriter',
]

# We are installing the PUDL module to build the docs, but the C libraries
# required to build snappy aren't available on RTD, so we need to exclude it
# from the installed dependencies here, and mock it for import in docs/conf.py
# using the autodoc_mock_imports parameter:
if not os.getenv('READTHEDOCS'):
    install_requires.append('python-snappy')

另一个可能的解决方案是将pudl包目录添加到conf.py中的sys.path中，这样即使没有安装，包也是可导入的。但是，我使用setuptools_scm自动生成一个版本号以供打包和文档使用，为此，需要将pudl包实际构建为发行版并进行安装。