ClimateMachine Documentation

Documentation Overview

ClimateMachine.jl uses Documenter.jl to convert markdown + extensions markup to html.

Literate.jl is used for generating markdown and rendered plot images for tutorials to be included with the Documenter.jl build.

Previewing Local Documentation Builds

HTML assets are rendered in docs/src/generated/ sub directory and can be opened locally with a compatible modern webbrowser.

Previewing Deployed Documentation Builds

Previews for PR's can be viewed at: https://clima.github.io/ClimateMachine.jl/previews/PR<number>

Infrastructure

ClimateMachine.jl uses two different systems to build documentation and upload documentation previews for PR's:

• GithubActions - Runs every pushed commit, every commit will kill any previously running stale builds. Doc builds run with tutorial generation disabled to limit the doc build / turnaround times.

• Buildkite - Runs doc builds on bors try and bors merge using Caltech's central cluster.
  Progress of triggered build pipelines can be monitored at https://buildkite.com/clima/climatemachine-docs. bors try runs will build tutorials in parallel in addition to API documentation after the tutorial assets are rendered. The built preview for bors try runs are pushed to the same preview URL as the PR preview URL. bors merge will build the docs but not update the PR preview. After the PR is merged through bors the docs are re-built on the master branch which updates the project dev documentation assets.

After a PR is closed another GithubAction is triggered to delete the generated PR preview assets. This prevents the accumulation of stale documentation build assets over time in the project repository git history.

Github Action build definition: https://github.com/CliMA/ClimateMachine.jl/blob/master/.github/workflows/Documenter.yaml Buildkite build definition: https://github.com/CliMA/ClimateMachine.jl/blob/master/.buildkite/docs-pipeline.yml