如何在ReadTheDocs中指定PlantUML的安装版本？

我在ReadTheDocs上托管的Sphinx项目中使用PlantUML，当前通过apt安装的是1.2020.2版本，缺少所需的新功能，需要指定安装最新版本。

当前配置情况 #

1. Sphinx的conf.py扩展配置 #

"sphinx.ext.graphviz",
"sphinxcontrib.plantuml",

2. .readthedocs.yaml配置 #

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

  apt_packages:
    - plantuml

sphinx:
  configuration: wiki/conf.py
  fail_on_warning: true

python:
  install:
  - requirements: wiki/requirements.txt

3. 构建日志显示安装旧版本 #

$ apt-get update --assume-yes --quiet
$ apt-get install --assume-yes --quiet -- plantuml
...
Get:46 http://archive.ubuntu.com/ubuntu jammy/universe amd64 plantuml all 1:1.2020.2+ds-1 [8035 kB]
...
Selecting previously unselected package plantuml.
Preparing to unpack .../45-plantuml_1%3a1.2020.2+ds-1_all.deb ...
Unpacking plantuml (1:1.2020.2+ds-1) ...
...
Setting up plantuml (1:1.2020.2+ds-1) ...
...
done.

解决方法 #

Ubuntu 22.04（Jammy）的官方软件源中PlantUML版本滞后，无法通过apt获取最新版。可以通过手动下载指定版本的PlantUML Jar包并配置Sphinx来解决：

步骤1：修改.readthedocs.yaml #

移除apt安装PlantUML的配置，添加构建命令下载指定版本的Jar包，同时保留Java运行时（PlantUML依赖Java）：

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

  apt_packages:
    - openjdk-11-jre-headless  # 保留Java运行时环境

  commands:
    # 下载指定版本的PlantUML Jar包，此处以1.2024.6为例，可替换为需要的版本号
    - wget -O plantuml.jar https://github.com/plantuml/plantuml/releases/download/v1.2024.6/plantuml-1.2024.6.jar

sphinx:
  configuration: wiki/conf.py
  fail_on_warning: true

python:
  install:
  - requirements: wiki/requirements.txt

步骤2：修改Sphinx的conf.py #

配置plantuml命令指向下载的Jar包：

# 在conf.py中添加或修改以下配置
plantuml = 'java -jar /home/docs/checkout/plantuml.jar'

ReadTheDocs的构建工作目录为/home/docs/checkout，Jar包直接下载到该目录下，因此路径如上。

版本自定义 #

如果需要特定版本，只需修改wget命令中的版本号即可。例如要安装1.2023.12版本，对应的下载命令为：

wget -O plantuml.jar https://github.com/plantuml/plantuml/releases/download/v1.2023.12/plantuml-1.2023.12.jar

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