ReadTheDocs问题：__init__.py导入错误及Autodocs类文档为空

看起来你在ReadTheDocs用Autodocs的时候踩了两个坑：构建完类文档全空，还报了语法警告和__init__.py的导入错误。我之前也碰到过类似的问题，给你拆解下怎么解决：

一、关于print(clean_sample, file=open(new_fname, 'w'))的语法警告 #

你觉得这段代码没问题，但大概率是ReadTheDocs的构建环境和你本地的Python版本不一致！

• 如果你本地用的是Python 3.x，这段print带file=参数的写法是合法的，但如果RTD默认用了Python 2.x，print是个语句不是函数，这种写法直接就会触发语法错误警告。
• 解决办法：
  1. 强制RTD用Python 3：在docs/source/conf.py里添加路径配置和版本指定：

     import os
     import sys
     # 把项目根目录加入Python路径
     sys.path.insert(0, os.path.abspath('../../'))
     # 确保使用Python 3环境
     assert sys.version_info >= (3, 0), "Requires Python 3"
     

  2. 优化代码写法：顺便改掉直接open不关闭的不良习惯，用with语句更安全，还能避免潜在的资源泄漏：

     with open(new_fname, 'w') as f:
         print(clean_sample, file=f)
     

二、__init__.py的导入错误 #

导入错误是Autodocs解析失败的核心元凶——Autodocs必须能正确导入你的模块，才能提取类和函数的文档注释。常见原因和解决思路：

• 相对导入路径问题：如果__init__.py里用了相对导入（比如from .core import MyClass），但RTD的构建环境没把你的项目根目录加到Python路径里，就会找不到模块。
  解决：在conf.py里手动添加项目路径（刚才第一部分的代码已经包含这一步，重点确认路径是否正确）。
• 依赖库缺失：如果你的模块依赖第三方库（比如numpy、pandas），RTD构建环境默认不会安装这些依赖，导入时就会报错。
  解决：在项目根目录创建requirements.txt，把所有依赖列进去，然后在RTD的项目设置里找到「Install Project」选项，指定用这个文件安装依赖。
• __init__.py里的执行代码：如果__init__.py里有直接执行的代码（比如初始化配置、加载大文件），Autodocs导入模块时会执行这些代码，一旦出错就会导致导入失败。
  解决：把执行代码放到if __name__ == '__main__':块里，或者用autodoc_mock_imports在conf.py里mock掉有问题的依赖：

  # 替换成你实际需要mock的依赖/模块
  autodoc_mock_imports = ['numpy', 'pandas', 'some_external_lib']
  

三、验证和调试步骤 #

1. 本地先复现问题：在本地跑Sphinx构建命令，看看能不能复现同样的警告/错误，这样调试起来更高效：

   cd docs
   sphinx-build -b html source build/html
   

2. 检查RST文档指令：确认你的code.rst里的Autodocs指令是正确的，比如要提取某个类的文档，应该写：

   .. automodule:: medembed.your_module
      :members:
      :undoc-members:
      :show-inheritance:
   

   重点确保members参数已经开启，不然Autodocs不会提取类的成员文档。

把这些问题逐个解决后，重新触发RTD构建，应该就能正常生成类的文档了。

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