Key4hep documentation

Key4hep central documentation

Getting dependencies

Install python dependencies:

pip install -r requirements.txt

Building locally

First fetch the documentation pages from other key4hep repositories:

.github/scripts/fetch_external_sources.sh 

If the sources already exist but you want to update them, use the --force option.

Then build the site locally:

sphinx-build -M html docs build

Check the links validity with:

sphinx-build -b linkcheck docs linkcheck

Note, that we also build a preview of the page when you open a PR, so building locally might not be necessary.

Including changes from an external PR

In some cases the changes to the documentation happen in a different repository (as we include external resources here). It's possible to make the pipeline that builds the PR previews aware of this by using the phrase include PR for preview: <reference to the PR> in the body of the pull request. Currently only one such external PR is supported. Accepted formats for the PR reference are

• <github-org>/<repo>#<pr-number>
• url to the PR, i.e. https://github.com/<github-org>/<repo>/pull/<pr-number>

Deploying to github pages

The deployment to github pages happens via the gh-pages branch. On this branch the documentation goes into the main subdirectory, and we have a redirecting index.html.

The branch is automatically populated via github actions. However, its history is not really interesting (even though the action keeps it intact). In case the repository gets too large, it is possible to remove the branch entirely and start from scratch (the next run of the action will populate the branch again). Only the index.html file has to be put onto the branch first.

We also make preview pages for PRs on this repository which will be placed onto the gh-pages branch as well, but under a dedicated directory. This means that they are generally reachable by people, if they know the corresponding full reference.