sphinx autodoc 在 readthedocs 上创建空白页面，但在本地正确包含模块文档字符串答案

【问题标题】：sphinx autodoc creates blank page on readthedocs, but correctly includes module docstring locallysphinx autodoc 在 readthedocs 上创建空白页面，但在本地正确包含模块文档字符串
【发布时间】：2019-05-20 21:59:29
【问题描述】：

当我在本地运行 sphinx（Mac 版 Anaconda Python 3.6.8 上的版本 1.6.6 或 2.0.1）与在 readthedocs.org 上运行它时（根据他们的日志它是 Sphinx），我从 autodoc 得到不同的结果版本 1.8.5，可能还有 Python 2.7，因为它是使用 python 而不是 python3 启动的。

不同之处在于以下文件Shady.Text.rst 的结果，其中包含的内容不超过：

Shady.Text Sub-module
=====================

.. automodule:: Shady.Text

现在，这个子模块恰好只包含一个模块级别的文档字符串，而没有成员文档字符串——这符合预期，因此相应的 html 页面应该包含模块文档字符串，仅此而已。这正是我在本地运行make html 时发生的情况。但是https://shady.readthedocs.io/en/latest/source/Shady.Text.html 的结果是无内容的（只有标题，没有模块文档字符串）。

FWIW 我在 conf.py 中与 autodoc 相关的条目是：

autoclass_content = 'both'
autodoc_member_order = 'groupwise'

我做错了什么？

【问题讨论】：

检查build log 以获取这些警告WARNING: autodoc: failed to import module u'Text' from module u'Shady'; the module executes module level statement and it might call sys.exit(). WARNING: autodoc: failed to import module u'Video' from module u'Shady'; the module executes module level statement and it might call sys.exit(). looking for now-outdated files... none found。最有可能的是，您没有告诉 RTD 安装您的软件包。见docs.readthedocs.io/en/stable/…
@StevePiercy 谢谢，这让我走上了正轨（见答案）

标签： python-sphinx read-the-docs autodoc

【解决方案1】：

感谢@StevePiercy 让我注意到原始日志文件中的关键行：

WARNING: autodoc: failed to import module u'Text' from module u'Shady'; the module executes module level statement and it might call sys.exit().
WARNING: autodoc: failed to import module u'Video' from module u'Shady'; the module executes module level statement and it might call sys.exit().

（我已经在 9000 行的日志文件中搜索了 .Text，因为 Text 在其上产生了太多的点击，但我没有想到要在引号中搜索 'Text'。

对我来说，该消息具有误导性：问题不在于“模块执行模块级语句”，因为本身是允许的。在注意到 some 模块级语句似乎在其他子模块中被允许后，我浪费了一些时间，并试图将有问题的模块级语句捆绑到一个类装饰器中，认为可能是 sphinx 的神秘模块级-statement-detector 会错过它们......）

不，问题不在于模块级语句存在并且可能调用sys.exit()这一事实，而是它们确实间接调用@987654326这一事实@ 在 sphinx 的编译过程中。这是我处理缺失依赖项的方式的一个怪癖，可能应该重新考虑，但我现在可以通过避免我的sys.exit() 调用来解决它，当os.environ.get('READTHEDOCS') 是真的时。

【讨论】：