Repository navigation
Read the Docs build times out while compiling ABACUS to generate parameter documentation #8171
Description
Description
The abacus-rtd Read the Docs build for PR #8093 timed out before reaching Sphinx.
- Commit:
0a91abde60fed9a383dfb3b12f74d343ff854d81 - Failed build: https://app.readthedocs.org/projects/abacus-rtd/builds/35218892/
- Reported duration: 903 seconds
- RTD notification: “Build terminated due to time out.”
Where it stopped
CMake configuration succeeded with MPI and LCAO disabled:
cmake -Bbuild -GNinja -DCMAKE_INSTALL_PREFIX=install -DENABLE_MPI=OFF -DENABLE_LCAO=OFFThe build was terminated during:
cmake --build build --target install -j $(nproc)The available log contains no C++ compilation error. Parameter export and Sphinx had not started. The separate abacus-develop RTD check succeeded for the same commit, so the failure is not consistent across the two RTD projects.
Why documentation builds compile ABACUS
The current .readthedocs.yaml builds and installs ABACUS to generate the INPUT parameter documentation from the current code:
install/bin/abacus --generate-parameters-yaml > docs/parameters.yaml
python3 docs/generate_input_main.py docs/parameters.yamlThis makes documentation checks depend on a full executable build fitting within RTD's resource limits. ABACUS will support more abilities and the compiling time will be longer and longer.
Proposed next step
A lightweight parameter-export target, or generating the parameter documentation in GitHub Actions before rendering it on RTD.
Activity
Growl1234 commentedon Oct 18, 2026
I tried some attempts but failed. And some of them introduce complexity to CI workflow which I think shouldn't be the case. I'm not sure how to resolve the concern in a better way.
If RTD have some mechanism like API key, it should be possible to build document in GitHub Actions and deploy it to RTD webpage.
Growl1234 commentedon Oct 18, 2026
Good news: I found it have an direct upload approach. That said, adapting to this will mean dropping the currect RTD CI-workflow entirely and requiring a
READTHEDOCS_TOKEN.ABACUS-PR-BOT commentedon Oct 22, 2026
The timeout is confirmed, but it does not establish a compiler regression: the same
abacus-rtdproject subsequently built the same commit successfully (531 s, 587 s). The currentdevelopcommit75debc23also passed in 608 s.The failed run's 903 s is the reported build duration; its last build/install command has no retained timing or output. Parameter export and Sphinx are absent from the subsequent command records, so the precise cause of the timing variation remains unknown. The underlying concern still applies:
.readthedocs.yamlcompiles the configured ABACUS executable before exporting metadata. On the current successful run, build/install took about 475 s, while YAML export took under one second.A dedicated exporter reusing the existing registrations is a reasonable next engineering investigation, with same-commit output-equivalence and build-time checks; it has not yet been implemented or tested here. Direct upload is another option, currently beta requiring support enablement and a project-admin API token. It can be adopted per version while other versions retain RTD builds, though uploaded versions then need subsequent uploads. No builds or configuration changes were made in this investigation.
Growl1234 commentedon Oct 22, 2026
Some of my monitoring results may change the description above: I found sometimes a simple
apt-get installstep goes through 5-10min, which indicates that it's most likely an RTD runner issue. This issue is unable to be fixed from ABACUS side.