Sphinx构建在读取带有“未找到模块”错误的文档时中断，但在本地构建良好

Question

我试图在阅读文档的基础上构建文档，但我遇到了一个可怕的“未找到模块”错误。如果我在项目的根目录中本地发布make docs，一切都会正常运行，因此“未找到模块”错误对我来说非常奇怪

我正在使用PyPackageCookiecutter模板。以下是我的项目树的相关部分：

.
├── docs
│   ├── authors.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── history.rst
│   ├── index.rst
│   ├── installation.rst
│   ├── make.bat
│   ├── modules.rst
│   ├── readme.rst
│   ├── scattergrid.rst
│   └── usage.rst
├── requirements_dev.txt
├── scattergrid
│   ├── __init__.py
│   ├── cli.py
│   └── scattergrid.py
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── test_scattergrid.py
└── tox.ini

下面是同一项目中成功的本地生成在根目录中发出make docs：

Running Sphinx v3.0.4
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 9 source files that are out of date
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] usage
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] usage
generating indices...  genindex py-modindexdone
highlighting module code... [100%] scattergrid.scattergrid
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.
python -c "$BROWSER_PYSCRIPT" docs/_build/html/index.html

以下是读取文档时出现的错误：

Running Sphinx v1.8.5

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/checkouts/latest/docs/conf.py", line 20, in <module>
    import scattergrid
ModuleNotFoundError: No module named 'scattergrid'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/cmd/build.py", line 300, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/application.py", line 201, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 203, in read
    namespace = eval_config_file(filename, tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 380, in eval_config_file
    raise ConfigError(msg % traceback.format_exc())
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/checkouts/latest/docs/conf.py", line 20, in <module>
    import scattergrid
ModuleNotFoundError: No module named 'scattergrid'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/checkouts/latest/docs/conf.py", line 20, in <module>
    import scattergrid
ModuleNotFoundError: No module named 'scattergrid'

下面是在docs/conf.py中发生此错误的确切行

import scattergrid
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

这是由cookiecutter模板设置的，您可以看到绝对路径指向docs文件夹的上一层。如果我没有包含^{，那么一切都建立在阅读文档的基础上，但是当然，我没有任何真正的文档，因此任何帮助都将非常感谢

下面是从cookiecutter模板构建的docs/scattergrid.rst：

scattergrid package
===================

Submodules
----------

scattergrid.cli module
----------------------

.. automodule:: scattergrid.cli
   :members:
   :undoc-members:
   :show-inheritance:

scattergrid.scattergrid module
------------------------------

.. automodule:: scattergrid.scattergrid
   :members:
   :undoc-members:
   :show-inheritance:


Module contents
---------------

.. automodule:: scattergrid
   :members:
   :undoc-members:
   :show-inheritance: