Documentation

Automatic Doc Build

All ESMF technical documentation is built automatically through CircleCI on each commit to a branch, including develop. After a commit, on CircleCI find the build-esmf-docs job under the docs-commit workflow and click on the ARTIFACTS tab. The docs are available from there in a zip file for local download, if needed. The documentation is also automatically pushed to the ESMF web site.

• Docs are pushed to docs/nightly in the ESMF website repository.
• Docs are accessible at: http://earthsystemmodeling.org/doc/

Build Docs Locally

The CircleCI job about uses a set of Docker images that include all the dependencies for building the docs. Pre-built images are available on the ESMF DockerHub. To build the docs locally, use the docker commands below. (Otherwise, you will need to set up all the doc generation dependencies locally, which has proven to be a complex process.) The steps below are based on the automated commands seen in the CircleCI config.yml configuration file.

# install docker if not available, or use docker02.cgd.ucar.edu

# start with an empty working directory
cd /path/to/working/dir

# get base image with doc build dependencies
docker pull esmf/esmf-doc-base

# get docker image recipe for building docs
git clone https://github.com/ESCOMP/ESCOMP-Containers.git

# build the image  (set ESMF_BRANCH to desired branch from which to build docs)
docker build -t "esmf/esmf-doc:develop" --file "ESCOMP-Containers/ESMF/doc/esmf-doc/Dockerfile" --build-arg ESMF_BRANCH="develop" --build-arg DOCKER_NAMESPACE="esmf" --no-cache .

# copy the generated docs out of the container to a local directory
# /path/to/working/dir should be an absolute path on your local machine where the docs will be copied
docker run -v /path/to/working/dir:/host-machine esmf/esmf-doc:develop cp -r /artifacts /host-machine