Read the Docs用旧代码构建，autodoc报gfortran不存在错误求助

我之前也踩过类似的RTD构建坑，结合你描述的情况——注释了代码还报错、清理缓存没用，大概率是RTD默认从PyPI拉取了旧版本的wheel包，而非你GitLab仓库里的最新代码。下面是几个能快速解决的思路：

1. 强制RTD从Git仓库安装项目 #

RTD默认会优先从PyPI找你的项目包，哪怕你在仓库里更新了代码。要改掉这个行为，你需要在项目的.readthedocs.yaml配置文件里明确指定安装来源：

version: 2

python:
  install:
    # 强制从当前仓库目录安装，而非PyPI
    - method: pip
      path: .
    # 如果有文档专属依赖，可以加上这行
    - method: pip
      extra_requirements:
        - docs

如果还没创建.readthedocs.yaml，直接在项目根目录新建一个就行。这样RTD构建时会直接用你仓库里的最新代码，不会再去PyPI拉旧wheel。

2. 彻底清除RTD缓存，强制重建 #

有时候缓存会顽固残留，光清理版本缓存不够：

• 在RTD的项目构建页面，选择Rebuild with clean选项（这个选项会完全清空之前的缓存，重新拉取代码、安装依赖）；
• 也可以在配置文件里直接禁用缓存：

  build:
    cache:
      enabled: false
  

3. 优化代码层面的规避逻辑 #

之前用if not 'sphinx' in sys.modules的判断可能不够可靠，因为autodoc运行时sphinx已经在sys.modules里了。换用RTD专属的环境变量判断会更准确：

import os

# 只有非RTD环境才执行需要gfortran的代码
if os.environ.get('READTHEDOCS') != 'True':
    # 这里放触发gfortran的代码，比如编译Fortran扩展等

另外，建议把需要编译的功能和文档依赖拆分，比如在setup.py或pyproject.toml里用extras_require，让RTD只安装文档所需的轻量依赖，完全跳过编译步骤。

4. 检查构建日志确认安装来源 #

去RTD的构建日志里找安装阶段的输出，如果看到类似Collecting your-package且指向PyPI的链接，说明还是从PyPI拉的包；如果看到Processing ./或Installing from local directory，才是正确使用了仓库代码。通过日志能快速定位问题是否真的出在安装源上。

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