Sphinx autodoc本地正常但Read The Docs无法识别Python包

针对你遇到的RTD构建时无法识别rtdtest包的问题，给出以下针对性解决步骤：

1. 补充项目安装配置文件 #

你已勾选RTD的「Install Project」选项，但如果项目缺少标准安装配置文件，RTD无法正确将包安装到构建环境中，这是最可能的核心原因。

添加pyproject.toml到仓库根目录，内容如下：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "rtdtest"
version = "0.1.0"
packages = ["rtdtest"]

或者创建setup.py（兼容旧版工具）：

from setuptools import setup, find_packages

setup(
    name="rtdtest",
    version="0.1.0",
    packages=find_packages(),
)

二者选其一即可，它们会告诉RTD如何安装你的rtdtest包。

2. 优化conf.py的sys.path配置 #

本地的相对路径配置在RTD环境中可能存在解析问题，替换为更鲁棒的写法：

import sys
from pathlib import Path

# 从conf.py所在目录向上回溯到仓库根目录
sys.path.insert(0, str(Path(__file__).parent.parent.parent))

这种写法不依赖固定层级，能适配不同环境的路径结构。

3. 验证RTD构建日志 #

提交修改后触发RTD重新构建，查看日志中的安装步骤：

• 若日志出现Installing collected packages: rtdtest相关内容，说明包已成功安装
• 若没有安装步骤输出，检查RTD高级设置中「Install Project」是否仍处于勾选状态

额外排查点 #

• 确认rtdtest目录下的__init__.py确实存在（你已提到有空白文件，可快速跳过）
• 避免在conf.py中使用硬编码绝对路径，保证配置通用性

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