Merge pull request #10 from uclahs-cds/nwiltsie_render_docs

Add (reworked) action to build and deploy documentation website

CHANGELOG.md

@@ -8,6 +8,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ---
 
 ## [Unreleased]
+### Added
+- Action to build and deploy documentation on GitHub Pages
+
 ### Changed
 - Update output file name to explicitly specify `submodules`
 

build-and-deploy-docs/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12.1
+
+COPY action.sh create_mkdocs_config.py requirements.txt /src/
+
+RUN python -m pip install --no-cache-dir -r /src/requirements.txt && \
+    chmod +x /src/action.sh
+
+ENTRYPOINT ["/src/action.sh"]
+
+LABEL maintainer="Nicholas Wiltsie, [email protected]"

build-and-deploy-docs/README.md

@@ -0,0 +1,38 @@
+# Build and Deploy Pipeline Documentation
+
+This Github Action builds a documentation website and deploys it to [GitHub Pages](https://pages.github.com/) for the UCLAHS-CDS pipelines using [MKDocs](https://www.mkdocs.org/).
+
+The pipeline's README.md is split into individual pages based on [level 2 headings](https://www.markdownguide.org/basic-syntax/#headings). A MkDocs config yaml file can also be used to specify specific parameters including additional documentation. Documentation must be written in Markdown syntax.
+
+## Example
+
+```yaml
+---
+name: Build and Deploy Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+
+      - name: Deploy docs
+        uses: uclahs-cds/tool-Nextflow-action/build-and-deploy-docs@main
+```
+
+## Parameters
+
+Parameters can be specified using the [`with`](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runsstepswith) option.
+
+| Parameter | Type | Required | Description |
+| ---- | ---- | ---- | ---- |
+| `readme` | string | no | Relative path to the README file. Defaults to 'README.md' |
+| `mkdocs_config` | string | no | Relative path to the MKDocs config yaml. |

build-and-deploy-docs/action.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+set -euo pipefail
+
+MKDOCS_CONFIG=$1
+README=$2
+
+set_git() {
+    # see https://github.com/actions/checkout/issues/766
+    git config --global --add safe.directory "${GITHUB_WORKSPACE}"
+
+    git config --global user.name "${GITHUB_ACTOR}"
+    git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+    # See https://github.com/jimporter/mike/tree/af47b9699aeeeea7f9ecea2631e1c9cfd92e06af#deploying-via-ci
+    git fetch origin gh-pages --depth=1
+}
+
+build_and_deploy() {
+    config_file=${GITHUB_WORKSPACE}/mkdocs.yml
+
+    # Create a new commit on the gh-pages branch with documentation from this
+    # version and alias that as "latest"
+    mike deploy \
+        --config-file "$config_file" \
+        --update-aliases \
+        "$(git describe --tags --always)" \
+        latest
+
+    # Redirect from the base site to the latest version. This will be a no-op
+    # after the very first deployment, but it will not cause problems
+    mike set-default \
+        --config-file "$config_file" \
+        latest
+
+    # Push up the changes to the docs
+    git push origin gh-pages
+}
+
+main() {
+    set_git
+    python /src/create_mkdocs_config.py \
+        --pipeline-dir "${GITHUB_WORKSPACE}" \
+        --pipeline-repo "${GITHUB_REPOSITORY}" \
+        --mkdocs-config "${MKDOCS_CONFIG}" \
+        --readme "${README}"
+    build_and_deploy
+}
+
+main

build-and-deploy-docs/action.yml

@@ -0,0 +1,20 @@
+---
+name: 'Render and deploy docs'
+description: 'Render pipeline documentation and deploy to GH-Pages'
+inputs:
+  readme:
+    description: 'Relative path to the README file.'
+    required: false
+    default: 'README.md'
+  mkdocs_config:
+    description: 'Relative path to the MkDocs config yaml.'
+    required: false
+    default: 'None'
+
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  entrypoint: '/src/action.sh'
+  args:
+    - ${{ inputs.mkdocs_config }}
+    - ${{ inputs.readme }}