CoolProp 文档构建完全指南:本地 Sphinx/Doxygen 双轨构建与 CI 自动化发布

原创2026-10-13 13:07:281,456 阅读
文章标签:科学计算科研高性能计算跨平台

CoolProp 文档构建完全指南:本地 Sphinx/Doxygen 双轨构建与 CI 自动化发布

CoolProp 是一个开源热物性数据库,其官方文档由两套工具链共同产出:Sphinx 负责把 reStructuredText(.rst)源文件与可动态执行的 iPython 示例编译成 HTML 站点,Doxygen 负责把 C++ 源码注释编译成 API 参考手册。本文以 Web/develop/documentation.rst 为核心骨架,完整还原在 Linux / macOS / Windows 三平台上从零构建 CoolProp 文档的每一步操作,并结合仓库内真实的构建脚本(Web/Makefile、Web/scripts/__init__.py、Web/conf.py)与 GitHub Actions 工作流(.github/workflows/docs_docker-run.yml)讲清底层原理。读完本文,你将能复现官方文档站点、调试自己新增的文档页面,并理解 CI 中"构建 → 校验链接 → 发布到 GitHub Pages"的完整流水线。

一、CoolProp 文档体系概览:Sphinx 与 Doxygen 双轨并行

CoolProp 的在线文档(https://coolprop.org)并不是手工维护的静态 HTML,而是通过自动化流水线生成的。其技术栈可以概括为:

  • Sphinx:把 Web/ 目录下一整套 .rst 源文件转换为 HTML。reStructuredText 语法便于编辑与版本管理;更关键的是,文档中嵌入了大量可执行的 iPython 示例,构建时会用最新构建出的 CoolProp 版本动态执行这些示例,并把真实运行输出渲染进最终的 HTML 页面,保证文档中的数值结果与当前源码一致。
  • Doxygen:从 Doxyfile 指定的配置出发,把 include/、src/ 等目录下的 C++ 源码注释编译成 API 参考文档(通过 Sphinx 的 sphinxcontrib.doxylink 扩展与 HTML 站点联动)。

文档源文件的组织方式可以在 Web/contents.rst 与 Web/develop/index.rst 中看到:根文档 contents.rst 通过 toctree 把 general_information、online、fluid_properties、coolprop、develop 等章节串成整体,而开发者文档一章(develop/index.rst)又分别指向 code.rst、backends.rst、cmake.rst、documentation.rst(即本文所述内容)、release.rst、testing.rst、web2py_online.rst。

也就是说,本文讨论的 documentation.rst 本身就是这个文档站点中"如何构建文档"的自举说明——用 Sphinx 文档来教你怎么构建 Sphinx 文档。

二、构建前置:搭建 conda 文档环境

无论是本地构建还是 CI 构建,所有依赖的"权威清单"都集中在仓库根目录的 dev/docker/conda_environment.yml 中——这份文件与 CI 构建容器所用的环境完全同源。其内容可分为两组:

conda-forge 渠道的科学计算栈(Python 3.13):

包名 作用
scipy / numpy 文档中大量计算型示例的数值基础
matplotlib 生成物性曲线图(plot_directive 扩展依赖)
plotly 交互式绘图示例(如 SVDSBTL 验证 notebook)
joblib SVDSBTL 表格的并行构建
ipython / jupyter / notebook / nbconvert 执行与渲染 .ipynb notebook
pandas / openpyxl 表格数据处理示例
pandoc 文档格式转换
imagemagick 图片处理
requests / jinja2 / pyyaml / packaging / six 构建脚本与 Sphinx 插件的运行时依赖

pip 安装的 Sphinx 生态:

  • sphinx 本体
  • sphinxcontrib-napoleon(解析 NumPy/Google 风格 docstring)
  • sphinxcontrib-doxylink(连接 Doxygen tag 文件,实现与 Doxygen 文档的交叉引用)
  • sphinxcontrib-bibtex(参考文献引用)
  • cloud_sptheme(文档主题,需配合 dev/docker/patch_cloud_sptheme.py 修复 jinja2 导入路径)
  • nbsphinx(把 notebook 嵌入 Sphinx 文档)
  • sphinx-design(Sphinx 设计组件)

用 conda 复现环境的命令如下(环境名固定为 docs):

conda env create -f dev/docker/conda_environment.yml
conda activate docs   # the environment is named "docs"

在 macOS 上的额外前置步骤(原文档步骤 0):需要可用的 LaTeX 发行版以及若干命令行工具:

brew install jpeg libpng libtiff libtool imagemagick

并在 ~/.bash_profile 中补充本地化环境变量,否则中文字符集相关处理可能报错:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

2.1 安装与文档匹配的 CoolProp Python wheel

文档中嵌入了大量示例代码,构建时必须使用同一份 checkout 构建出来的 wheel,保证示例输出与文档版本一一对应:

pip wheel .
pip install ./CoolProp-*.whl

这一步在 CI 中对应 docs_docker-run.yml 的 "Build and install wheel using bdist_wheel" 步骤:先运行 python dev/generate_headers.py 生成头文件,再 pip -vv wheel . 构建、以 --force-reinstall --ignore-installed --no-index 强制安装本地产物,随后用 python -c "import CoolProp; print(CoolProp.__version__)" 等命令验证安装结果。

三、Sphinx 文档本地构建(五步走)

按原文档步骤,所有命令默认在仓库根目录执行,构建 Sphinx 文档的完整链路为:

Step 1:获取源码

git clone https://gitcode.com/gh_mirrors/co/CoolProp
cd CoolProp

Step 2:创建构建环境(见上文第二节)

conda env create -f dev/docker/conda_environment.yml
conda activate docs
pip wheel .
pip install ./CoolProp-*.whl

Step 3:运行 setup 脚本生成动态内容

cd Web/scripts
python __init__.py
cd ..

Step 4:在 Web 目录下构建 HTML

make html

Step 5:迁移产物——生成的文档位于 _build 目录,可将其移动到任何你想要的位置。

3.1 make html 到底做了什么:解读 Web/Makefile

make html 的实际执行内容定义在 Web/Makefile 中:

SPHINXBUILD   = sphinx-build
ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
html:
	$(SPHINXBUILD) -j auto -T -b html $(ALLSPHINXOPTS) _build/html

可以看到默认调用的是 sphinx-build -j auto -T -b html:-j auto 启用多核并行(文档页很多,并行能显著提速),-T 输出完整 traceback 便于调试,-b html 指定 HTML builder,产物写入 _build/html。Makefile 中还保留了 html_release(带 -t Release 标签的发布构建)、dirhtml、pickle、json、latex、linkcheck、doctest 等多个 target,其中 linkcheck 会在 CI 中用于死链检测(详见第七节)。

3.2 构建期内发生了什么:Sphinx 配置与 notebook 执行

make html 启动后,Web/conf.py 会在构建早期完成大量准备工作:

  • 版本注入:import CoolProp 后读取 CoolProp.__version__,并通过 rst_prolog 把 num_pure_fluids 等替换变量注入所有 .rst 页面。

  • nbconvert 预执行所有 notebook:conf.py 会遍历 Web 下所有 .ipynb(排除 _build 与 ipynb_checkpoints),执行

    jupyter nbconvert --allow-errors --ExecutePreprocessor.timeout=3600 --to notebook --output ... --execute ...
    

    timeout 从 nbconvert 默认的 30 秒调高到 1 小时,是为了容纳首次运行需要冷构建磁盘缓存的 notebook(典型如 SVDSBTLValidation.ipynb,每个流体构建 SVDSBTL 表面约需 20–80 秒)。

  • 本地化第三方资源:下载 MathJax 4.0.0 并解压到 _static/MathJax-4.0.0,下载 3Dmol.js 2.5.4 到 _static/3Dmol-min.js(流体页面需要交互式分子查看器),并设置 html_js_files 的加载优先级为 450,确保在 require.js(优先级 500)之前加载。

  • 扩展注册:sphinx.ext.intersphinx、autodoc、mathjax、extlinks、sphinxcontrib.bibtex、napoleon、doxylink、matplotlib.sphinxext.plot_directive、nbsphinx、sphinx_design 等扩展共同参与渲染。

  • 主题:使用 pydata_sphinx_theme,并通过 edit_on_github_project = 'CoolProp/CoolProp' 为每个页面挂上 "Edit on GitHub" 跳转。

3.3 setup 脚本:Web/scripts/__init__.py 的任务清单

第三步执行的 python __init__.py 是整个动态内容生成的枢纽,见 Web/scripts/init.py。它会把一批 Python 脚本依次加入任务列表并逐个执行,典型任务包括:

脚本 生成的动态内容
coolprop.tabular.speed.py 表格插值速度基准
fluid_properties.phase_envelope.py 相包络线图
fluid_properties.PurePseudoPure.py / Mixtures.py / PredefinedMixtures.py 纯流体、混合物页面
fluid_properties.Superancillary.py 超辅助方程验证数据
coolprop.parametric_table.py 参数表示例
coolprop.configuration.py 配置项文档
logo_2014.py 站点 Logo 图
fluid_properties.REFPROPcomparison.py / IF97Conformance.py / IF97Profile.py 与 REFPROP、IF97 的对比验证页
fluid_properties.Consistency.py 每个流体的热力学一致性报告图(增量执行:已存在 PNG 的流体直接跳过,因此缓存恢复后的重复构建几乎是空操作)

脚本支持一个布尔参数控制"完整重建":python __init__.py true(或 1)时,full_rebuild = True,会额外设置环境变量 COOLPROP_FORCE_CONSISTENCY=1 并执行昂贵的 fluid_properties.Incompressibles.sh。CI 中正是用 COOLPROP_EXPENSIVE 这个环境变量来动态决定是否传入该参数。

此外,__init__.py 还会把当前 CoolProp 版本追加写入仓库根目录的 Doxyfile(PROJECT_NUMBER = <version>),让 Doxygen 产物的版本号始终与 Sphinx 文档一致——这也是先跑 __init__.py 再跑 doxygen 的原因之一。

3.4 wrapper 示例的动态编译

除了 Python 计算脚本,setup 还会通过平台分派脚本(Linux 下为 dev/scripts/examples/LinuxRun.py)动态编译并运行各语言 wrapper 的示例,把输出回填到文档的 Web/coolprop/wrappers 页面中。该脚本对 Python、Octave、Java、C#、R 分别执行"生成示例源码 → cmake 编译对应模块 → 运行示例 → 拷贝 Example.<ext> 与 Example.out 到文档目录"的完整流程,例如 Octave 模块的编译命令:

cmake ../../.. -G Ninja -DCOOLPROP_OCTAVE_MODULE=ON -DCOOLPROP_NO_EXAMPLES=ON
cmake --build .
octave Example.m

脚本还检测 ccache 是否存在,存在时通过 -DCMAKE_CXX_COMPILER_LAUNCHER=ccache 给核心库编译加速(每次为一种 wrapper 语言都要完整编译一遍 CoolProp 核心,ccache 让跨构建复用成为可能)。如果本机缺少 Octave、Java 等可选运行时,对应示例会被跳过并给出可忽略的警告,不影响整体构建。

四、Doxygen API 文档构建

CoolProp 的 C++ API 文档全部由 Doxyfile 控制。该文件是标准 Doxygen 1.8.7 配置,关键项包括 PROJECT_NAME = CoolProp、PROJECT_BRIEF = "An open-source fluid property and humid air property database",而 PROJECT_NUMBER 会被 Web/scripts/__init__.py 动态覆盖为当前 CoolProp 版本号。

构建步骤只有两条:

  1. 安装 doxygen:Linux 下 sudo apt-get install doxygen 即可;其他平台从 doxygen 官方发布页下载对应安装包。
  2. 在仓库根目录执行:
doxygen Doxyfile

产物默认输出到 Doxyfile 中 OUTPUT_DIRECTORY 指定的位置。在 CI 中,doxygen Doxyfile 是在激活 docs 环境后、Sphinx 构建之前执行的(见第七节),生成的 tag 文件与 HTML 会被 Web/conf.py 中的 doxylink 配置(cpapi 指向 _static/doxygen/CoolPropDoxyLink.tag)引用,从而实现文档正文到 C++ API 参考的交叉链接。

五、在 Linux 上构建文档

Linux(Debian/Ubuntu 系)构建与通用流程完全一致,只需先补齐系统级依赖:

sudo apt-get install build-essential imagemagick git gfortran cmake doxygen pandoc python3-dev python3-pip
sudo apt-get install libblas-dev liblapack-dev   # numpy / scipy
sudo apt-get install libpng-dev tk libfreetype6-dev  # matplotlib

装完系统包后,继续按照第二、三节的步骤:创建 conda 环境 → 安装匹配的 wheel → python Web/scripts/__init__.py → make html。这些 apt 包与 docs_01_base.Dockerfile(dev/docker/docs_01_base.Dockerfile)中预装的 g++ make cmake ninja-build swig doxygen p7zip-full ccache mono-mcs octave r-base-dev default-jre/jdk texlive-extra-utils rsync 高度对应——该 Dockerfile 正是 CI 基础容器的定义。

六、在 Windows 上构建文档

Windows 构建与 Linux/macOS 走同一条路径:用 conda 环境 + 匹配的 wheel + setup 脚本 + make html。conda(Miniconda 或 Anaconda)是获得一套干净、带 MKL 加速的科学计算 Python 栈最省事的方式。

前置条件:

  1. 安装 GNUwin32 Make:从 GNUwin32 项目页下载安装后,把 C:\Program Files (x86)\GnuWin32\bin 加入 PATH 环境变量,保证任意命令行窗口都能执行 make。
  2. 安装 64 位 Miniconda(或 Anaconda),然后在仓库根目录创建构建环境:
conda env create -f dev/docker/conda_environment.yml
conda activate docs
  1. (可选)wrapper 示例依赖:若想在文档中生成 wrapper 示例,需要安装这些示例依赖的软件(如 Octave、REFPROP 等);未安装时相关示例会被跳过并输出可忽略的警告。

运行 setup 脚本:

打开命令提示符,激活 docs 环境,进入 CoolProp\Web\scripts:

conda activate docs
python __init__.py

(Linux/macOS 使用同一个入口,见 Web/scripts/init.py。)这些脚本只需运行一次,部分脚本可能根据已安装的可选包输出警告,属正常现象。

构建文档:

在 CoolProp\Web 目录、docs 环境激活状态下:

make html

构建完成后会生成 CoolProp\Web\_build 目录,用任意浏览器打开 _build\html\index.html 即可查看。make 会跳过未变更的部分实现增量构建;如需清理使用 make clean,要强制全新构建则使用:

make clean html

七、CI 自动化:GitHub Actions 中的完整流水线

官方文档站点并非手工构建,而是由 .github/workflows/docs_docker-run.yml 驱动。这条工作流揭示了文档构建的全部自动化细节,值得逐段拆解:

触发条件:每天两次定时(cron 0 2 * * * 日构建、0 4 * * 1 周构建)、workflow_dispatch 手动触发(可勾选 "Build expensive docs")、push 到 master/main/develop/actions_docs 分支及 v* tag、针对主要分支的 PR。

运行环境:任务在 ghcr.io/coolprop/coolprop_docs_02_builder:dev 容器内运行。这个容器由两阶段 Dockerfile 构建:

  • dev/docker/docs_01_base.Dockerfile(公开基础镜像):miniconda3 + 全套编译工具链 + conda 环境。
  • dev/docker/docs_02_builder.Dockerfile(不可公开,因为内置了 REFPROP):在第一阶段基础上,先以多阶段构建方式从 REFPROP 源码编译 librefprop.so 并安装到 /opt/refprop,供文档中的 REFPROP 对比示例使用。

关键步骤序列:

  1. 缓存策略:三个 actions/cache 分别缓存一致性报告图(Web/fluid_properties/fluids/Consistencyplots 等,键随流体 JSON 文件哈希失效)、SVDSBTL 表面表(通过 COOLPROP_ALTERNATIVE_SVDTABLES_DIRECTORY 指向工作区内目录,避免放在容器 home 导致无法缓存)、以及 wrapper 编译用的 ccache 目录。SVDSBTL 缓存特意不设 restore-keys 回退,防止部分恢复引入与 EOS/算法不一致的陈旧表面。
  2. 构建并安装 wheel:python dev/generate_headers.py + pip wheel . + 强制安装,随后验证 CoolProp.__version__ / __gitrevision__。
  3. 运行 setup 脚本:python -u __init__.py ${{ env.COOLPROP_EXPENSIVE }}——COOLPROP_EXPENSIVE 由"缓存未命中 / 手动勾选 / tag / 周构建"任一条件置真,从而触发完整重建。
  4. 构建 Doxygen:doxygen Doxyfile。
  5. 构建 Sphinx:先 sphinx-apidoc 生成 Python API 文档骨架(显式排除多年未更新的 wxPython GUI 模块),再 make html。
  6. 非阻塞链接检查:make linkcheck SPHINXOPTS=-q,从 _build/linkcheck/output.txt 中提取 [broken] / [timeout] 条目并以 continue-on-error: true 运行——外部站点波动不构成硬性失败。Web/conf.py 中的 linkcheck_ignore、linkcheck_request_headers(伪装浏览器 UA)与 linkcheck_timeout 等配置用于压减误报。
  7. 归档与发布:HTML 产物打成 CoolProp-<version>-documentation-html.tar.gz 上传为 artifact;只有 tag 触发的构建才会通过 actions/deploy-pages 发布到 GitHub Pages。另有一个独立的 .github/workflows/docs_devdocs-run.yml 负责在推送 master/main 或 tag 时通过 GitHub App 令牌触发 devdocs 仓库的部署。

八、常见问题与排查建议

  • wrapper 示例缺失:构建日志中出现"example skipped with warnings"时,多为本机未装 Octave、Java、REFPROP 等可选软件。这些警告可安全忽略,dev/scripts/examples/LinuxRun.py 对缺少的模块做了容错。
  • import CoolProp 失败或版本不符:文档构建强依赖"与当前 checkout 匹配"的 wheel。请确认已按第二节执行 pip wheel . 且 conda activate docs 生效;CI 中这一步失败会直接体现在 "Test the installed CoolProp version" 步骤。
  • notebook 执行超时:conf.py 已把 nbconvert 超时调至 3600 秒以容纳 SVDSBTL 冷缓存构建;若新增 notebook 仍超时,应检查是否存在"看似卡死一小时的 notebook"。
  • Doxygen 版本号不对:请先运行 python Web/scripts/__init__.py 再执行 doxygen Doxyfile——版本号正是在 setup 阶段注入 Doxyfile 的。
  • linkcheck 误报:外部站点对自动化请求返回 403/429 是常态,conf.py 中的 linkcheck_ignore 与 linkcheck_request_headers 已经覆盖了已知"硬封锁"站点,若新增域名需自行补充规则。

小结

CoolProp 的文档构建是一个典型的"文档即工程"实践:Web/develop/documentation.rst 描述的步骤背后,是一套由 conda 环境清单、动态内容生成脚本、Sphinx/Doxygen 双 builder、容器化 CI 与三层缓存构成的完整流水线。无论是本地 make html 快速预览,还是跟随 CI 复现官方发布流程,只要严格按"环境 → wheel → setup 脚本 → make"的顺序执行,并留意平台差异(macOS 的 LaTeX、Windows 的 GNUwin32 Make),就能得到与官方站点一致的、数值可复现的 CoolProp 文档。

登录后查看全文
CoolProp