EOEPCA Deployment Guide

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.

Material Theme

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.

Helper Script - serve

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/.

GitHub Action

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.

Public Domain - deployment-guide.docs.eoepca.org

The contents of the gh-pages branch are published via the domain deployment-guide.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 deployment-guide.docs.eoepca.org
2. Follow the GitHub steps to verify ownership of the domain deployment-guide.docs.eoepca.org
3. Maintain the file docs/CNAME with the domain name

Helper Script - publish

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

Mkdocs is configured to support versioning by using the mike plugin.

Examples

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

./publish current latest

Publish to v1.x version...

./publish v1.x

Other Helper Scripts

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