Sphinx生成Node.js库文档在Read the Docs编译失败求助

问题分析 #

你遇到的两个核心问题：

• 编译时找不到sphinx_rtd_theme模块
• 添加requirements.txt后，Read the Docs错误地尝试将你的Node.js库当作Python包安装

解决方案 #

1. 正确配置requirements.txt #

在项目根目录创建requirements.txt，只写入Sphinx文档需要的Python依赖：

sphinx
sphinx_rtd_theme

2. 修改.readthedocs.yaml，禁止安装项目本身 #

更新配置文件，明确指定依赖文件，并添加python.install配置，只安装依赖而不尝试安装项目：

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
    # 启用Node.js，若文档生成依赖Node.js环境则取消注释
    nodejs: "19"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
   configuration: docs/conf.py

# 配置Python依赖安装，仅安装requirements.txt中的包，不安装项目
python:
  install:
    - requirements: requirements.txt

3. 简化conf.py的主题配置 #

sphinx_rtd_theme是HTML主题而非Sphinx扩展，不需要加到扩展列表里，简化后的conf.py如下：

project = 'My-Library'
copyright = '2023, Hector E. Socarras'
author = 'Hector E. Socarras'
release = '1.0.0'

# -- General configuration ---------------------------------------------------
extensions = ['sphinx.ext.autosectionlabel']

templates_path = ['_templates']
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# -- Options for HTML output -------------------------------------------------
html_theme = "sphinx_rtd_theme"
html_static_path = ['static']

错误原因说明 #

• 最初找不到sphinx_rtd_theme是因为Read the Docs构建环境未预装该主题，而你本地已安装
• 添加requirements.txt后，Read the Docs默认会执行pip install .尝试安装项目，但你的Node.js库没有Python打包文件（setup.py/pyproject.toml），因此报错
• 把sphinx_rtd_theme放在extensions列表中是错误操作，会导致Sphinx尝试将其作为扩展导入，进一步触发异常

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