dmlc / dmlc/xgboost

Improving online document build process.

Open
#11,252 2 comments 0 reactions 0 assignees View on GitHub
CI doc
Dominant language
C++
Stars
28.8k
Forks
8.9k
Avg merge
1d 12h
Merged PRs (30d)
54

Description

This is a short note in companion with https://github.com/dmlc/xgboost/blob/master/doc/contrib/docs.rst#read-the-docs .

There are subtle differences between building docs for PR and for dmlc branches, including release branches and the master branch. The RTD build process is run twice, the first triggered by the GitHub webhook and the second by XGBoost GitHub action using the REST API. We can't avoid the first run, as the webhook has to be enabled. Otherwise, RTD doesn't generate an online document for the previous.

Using the REST API requires an RTD token. However, since PR doesn't have permission to read GitHub secrets, the token is managed by GitHub and retrieved by the AWS secret manager during the build.

For PR branches, the first run will fetch possibly outdated pre-built R and JVM docs from the master branch's s3 bucket. It can do so by parsing the master branch's commit history. Then, the second run will access the correct artifact.

For the release branches and the master branch, the first run will result in a partial document as there's no fallback option.

Ideally, we should eliminate the first run altogether as it's useless. These are some potential solutions we can look into:
- A feature request for RTD to integrate the build trigger with GitHub action. Related https://github.com/readthedocs/readthedocs.org/issues/1083 .
- Use an independent website for non-sphinx documents, and hardcode the links in our sphinx doc.
- Use an independent website for all the doc.
- Integrate the doc build into RTD, maybe with some help from Conda for binary R packages.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.