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.

NOTE: docker tags do not allow slashes, so even though you may build the docs for a specific branch, you may not be able to tag the docker image with the same tag.

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

# start with an empty working directory
# </path/to/working/dir> should be an absolute path on your local machine where the docs will be copied
cd </path/to/working/dir>

# get docker image recipe for building docs
git clone https://github.com/esmf-org/esmf-containers.git

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

# copy the generated docs out of the container to a local directory
docker run -v </path/to/working/dir>:/host-machine esmf/esmf-doc:develop cp -r /artifacts /host-machine

Build ESMPy Docs Locally

ESMPy documentation can be built in a similar way as ESMF documentation using Docker.

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

# start with an empty working directory
# </path/to/working/dir> should be an absolute path on your local machine
cd </path/to/working/dir>

# get docker image recipe for building docs
git clone https://github.com/esmf-org/esmf-containers.git

# build the image
# <TAG> is a branch or tag of the esmf repo
docker build -t "esmf/esmpy-doc:<TAG>" --file "esmf-containers/build-esmf-docs/esmpy/Dockerfile" --build-arg ESMF_BRANCH=<ESMF_TAG> --build-arg --no-cache .

# copy the generated docs out of the container to a local directory
docker run -v </path/to/working/dir>:/host-machine esmf/esmpy-doc:<ESMF_TAG> cp -r /artifacts /host-machine