The guide is written in Markdown and rendered through the mkdocs tool.

The file mkdocs.yml is the configuration file that describes the organisation and settings for the document generation.

The documentation is rendered with the Material Theme.

To avoid the need for a local installation of the mkdocs tooling and the Material for MkDocs theme, we have some local helper scripts that use a docker image squidfunk/mkdocs-material for this tooling.

The script ./serve is used for local development of the docs - using the squidfunk/mkdocs-material docker image to invoke a local server to render the 'live' content from the docs/ subdirectory.

The local document is served from http://localhost:8000/.

The GitHub Action at .github/workflows/main.yml is triggered on each commit pushed to origin/main to build the documentation to the branch gh-pages from where it is published.

The contents of the gh-pages branch are published via the domain system-description.docs.eoepca.org.

This is achieved by the steps:

1. Configure the GitHub pages to publish from the gh-pages branch and using the domain system-description.docs.eoepca.org
2. Follow the GitHub steps to verify ownership of the domain system-description.docs.eoepca.org
3. Maintain the file docs/CNAME with the domain name

This script is used to invoke publishing of the docs under a given version - by default the version current.

Examples

Publish to current version, and update the latest alias to point to this...

./publish current latest

Set current as the default...

./mike set-default --push current

Publish to v1.x version...

./publish v1.x

• mike
  Run mike via docker
• serve-published
  Serve the published site - i.e. the gh-pages branch