Build system documentation locally

This page explains how to build the system documentation locally

Install Julia

Documentation is build using Julia. It is strongly recommended that the official generic binaries from the downloads page be used to install Julia

Download Julia and untar
Add the julia bin directory to your PATH

export PATH=/path/to/julia/bin:$PATH

Note

On Atos you can

module load julia

but make sure to set JULIA_DEPOT_PATH to a place with sufficient quota. E.g set in .bashrc

export JULIA_DEPOT_PATH=$PERM/juliadepot

Install dependencies

To install the Documenter.jl dependency

julia --project=docs/ -e 'using Pkg; Pkg.instantiate()'

Build documentation

To create the HTML pages from the markdown files run

julia --project=docs/ docs/make.jl

[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Info: Deployment criteria for deploying devbranch build from GitHub Actions:
│ - ✔ ENV["GITHUB_REPOSITORY"]="github.com/Hirlam/HarmonieSystemDocumentation.git" occurs in repo="github.com/Hirlam/HarmonieSystemDocumentation.git"
│ - ✘ ENV["GITHUB_EVENT_NAME"]="" is "push"
│ - ✘ ENV["GITHUB_REF"] matches devbranch="pre-CY46h1"
│ - ✘ ENV["GITHUB_ACTOR"] exists
│ - ✘ ENV["DOCUMENTER_KEY"] or ENV["GITHUB_TOKEN"]  exists
└ Deploying: ✘

The HTML pages will be put in docs/build. Open index.html in a browser

firefox docs/build/index.html

A local build will not deploy the HTML pages to github.com/Hirlam/HarmonieSystemDocumentation.git.

Also see .github/workflows/documentation.yml