BornAgain ≻ git-develop ≻ Documentation ≻ Developers' corner ≻ Update documentation

Update documentation

This versioned documentation is built with Hugo from Markdown files in hugo/content/. The main website (news, downloads, and project information) is maintained in bornagain-www.

1. Edit the sources

Edit the Markdown files in hugo/content/. Keep lines within 80 characters.

2. Update changed examples and figures

Skip this step for text-only edits.

If you changed examples in rawEx/, regenerate the examples. Then, from the build directory:

  • ninja excopy copies scripts and data to hugo/static/py/auto/Examples/.
  • ninja figures regenerates all example figures in hugo/static/img/auto/. Run it for new images or to preview changed output; it can take a long time.

The committed script and data copies must match the generated examples, and referenced images must exist. CI regenerates figures before publication.

3. Preview locally

Install Hugo 0.158.0 or newer with your package manager or from the Hugo releases. From the repository root, start the preview if it is not already running:

cd hugo
hugo server --disableFastRender

Hugo prints a line such as:

Web Server is available at http://localhost:1313/25.0/ (bind address 127.0.0.1)

Open that URL to check the result. Leave Hugo running: it rebuilds the preview and refreshes the browser when you edit, add, or rename content files or directories.

--disableFastRender rebuilds all pages after changes, including navigation.

If changes are not reflected, stop Hugo with Ctrl+C and start it again. Restart it also when changing command-line options.

4. Check locally (optional)

CI runs the link and example-catalog checks automatically after a push. You can run them locally first to catch errors before waiting for CI.

For a quick internal-link check, run in another terminal from the repository root:

cd hugo/content
python3 ../../devtools/checks/check-hugo-links.py

If you already have a build with DEVELOPER_CHECKS=ON on Linux or macOS, you can instead run the link and example-catalog checks from its build directory:

ctest -R '^hugo\.' --output-on-failure

5. Publish through a merge request

Commit and push your changes, then open a merge request to the branch whose documentation you are updating.

After the merge, the versiondocs CI job runs ninja webdoc to build the site and examples ZIP. It publishes develop under /git-develop/ and release branches such as r25.0 under /25.0/.

Selecting a new latest version is part of Prepare a release.