如何在Read the Docs中通过makefile构建Sagemath包的Sphinx文档

两种方式都可以实现你的需求，具体操作如下：

方案1：直接通过Read the Docs（RTD）配置文件实现 #

RTD的YAML配置文件支持自定义构建命令，允许执行任意合法的shell操作，完全可以覆盖默认的Sphinx构建流程，你只需要在项目根目录下创建.readthedocs.yaml，按以下逻辑配置即可：

• 首先配置构建依赖，在apt_packages中添加sagemath，确保构建环境预装Sagemath
• 覆盖默认的构建命令，直接调用你需要的sage -sh -c "make html"执行构建
• 指定构建完成后的输出目录，让RTD正确识别生成的静态文档

示例配置参考：

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  apt_packages:
    - sagemath
  commands:
    # 可根据实际项目结构调整文档目录路径
    - cd docs
    - sage -sh -c "make html"
    # 指定构建输出目录，RTD会读取该目录下的文件作为最终文档
    - mkdir -p _readthedocs/html
    - cp -r docs/_build/html/* _readthedocs/html/

sphinx:
  # 关闭默认的Sphinx构建流程，使用自定义命令完成构建
  builder: none

如果你的项目对Sagemath版本有特殊要求，不需要使用apt源的默认版本，也可以在build.commands中添加手动下载编译指定版本Sagemath的指令，只是构建耗时会更长。

方案2：通过Makefile封装构建逻辑 #

如果你想把构建逻辑收敛到Makefile里也可以，只需要在文档目录的Makefile中新增一个专门的构建目标即可，示例：

rtd-build:
    sage -sh -c "make html"

之后只需要把.readthedocs.yaml里的构建命令替换为cd docs && make rtd-build即可，其余配置和方案1完全一致。

额外注意：如果你的Sagemath第三方包本身需要先安装才能构建文档，可以在构建文档的命令前先执行sage -pip install .完成包的安装，再执行文档构建步骤即可。

内容的提问来源于stack exchange，提问作者AS-q