本地Sphinx可生成autodoc成员文档，Read the Docs无法生成

以下是可能导致Read the Docs（RTD）上autodoc无法生成包成员文档的常见原因及解决办法：

1. Python路径未正确配置 #

本地开发时，项目根目录通常会被自动加入Python的sys.path，但RTD构建环境默认只会将docs目录加入路径，无法找到位于项目根目录的nix_shell_utils包。

解决办法：
在docs/conf.py开头添加以下代码，将项目根目录添加到Python路径：

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

这样Sphinx的autodoc就能正确找到并导入你的包。

2. RST文件未启用成员文档生成 #

检查docs/nix_shell_utils.rst中的automodule指令，确保添加了:members:选项，否则autodoc不会生成包内成员的文档：

nix_shell_utils module
======================

.. automodule:: nix_shell_utils
   :members:
   :undoc-members:  # 可选，用于包含无文档字符串的成员
   :show-inheritance:

如果本地配置了全局的autodoc_default_options包含members=True，但RTD的conf.py未同步该设置，也会导致此问题，需确保conf.py中有：

autodoc_default_options = {
    'members': True,
    'undoc-members': True,
}

3. RTD构建缓存干扰 #

RTD会缓存构建产物，若之前的错误构建结果被缓存，即使修复配置后也可能无法正常显示。

解决办法：
登录RTD后台，进入你的项目页面，在「Builds」选项卡中找到最新的构建记录，点击「Clear cache」后重新触发构建。

4. 包导入时的隐性问题 #

虽然你的包无外部依赖，但需确保__init__.py中没有依赖本地环境的代码（比如读取本地文件、执行系统命令等），这些代码在RTD构建环境中可能执行失败，导致autodoc无法完成导入。

验证方式：
在RTD构建日志中搜索autodoc相关的警告或错误，若存在导入失败的信息，需修改__init__.py中的代码，确保在Sphinx构建时能安全导入。

内容的提问来源于stack exchange，提问作者Alberto Garcia