CoolProp 文档构建完全指南:本地 Sphinx/Doxygen 双轨构建与 CI 自动化发布
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 版本号。
构建步骤只有两条:
- 安装 doxygen:Linux 下
sudo apt-get install doxygen即可;其他平台从 doxygen 官方发布页下载对应安装包。 - 在仓库根目录执行:
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 栈最省事的方式。
前置条件:
- 安装 GNUwin32 Make:从 GNUwin32 项目页下载安装后,把
C:\Program Files (x86)\GnuWin32\bin加入PATH环境变量,保证任意命令行窗口都能执行make。 - 安装 64 位 Miniconda(或 Anaconda),然后在仓库根目录创建构建环境:
conda env create -f dev/docker/conda_environment.yml
conda activate docs
- (可选)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 对比示例使用。
关键步骤序列:
- 缓存策略:三个
actions/cache分别缓存一致性报告图(Web/fluid_properties/fluids/Consistencyplots等,键随流体 JSON 文件哈希失效)、SVDSBTL 表面表(通过COOLPROP_ALTERNATIVE_SVDTABLES_DIRECTORY指向工作区内目录,避免放在容器 home 导致无法缓存)、以及 wrapper 编译用的 ccache 目录。SVDSBTL 缓存特意不设restore-keys回退,防止部分恢复引入与 EOS/算法不一致的陈旧表面。 - 构建并安装 wheel:
python dev/generate_headers.py+pip wheel .+ 强制安装,随后验证CoolProp.__version__/__gitrevision__。 - 运行 setup 脚本:
python -u __init__.py ${{ env.COOLPROP_EXPENSIVE }}——COOLPROP_EXPENSIVE由"缓存未命中 / 手动勾选 / tag / 周构建"任一条件置真,从而触发完整重建。 - 构建 Doxygen:
doxygen Doxyfile。 - 构建 Sphinx:先
sphinx-apidoc生成 Python API 文档骨架(显式排除多年未更新的 wxPython GUI 模块),再make html。 - 非阻塞链接检查:
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等配置用于压减误报。 - 归档与发布: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 文档。