feat: decouple docs release and introduce versioning

.github/workflows/docs-update.yml

@@ -0,0 +1,75 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+name: Trestle Docs update
+on:
+  push:
+    branches:
+    - develop
+    tags:
+    - v*
+
+jobs:
+  set-versions:
+    runs-on: ubuntu-latest
+    outputs:
+      min: ${{ steps.versions.outputs.min }}
+      max: ${{ steps.versions.outputs.max }}
+    steps:
+    - uses: actions/checkout@v4
+    - id: versions
+      run: |
+        min_version=$(jq '.PYTHON_MIN' -r version.json)
+        max_version=$(jq '.PYTHON_MAX' -r version.json)
+        echo "min=$min_version" 
+        echo "max=$max_version"
+        echo "min=$min_version" >> $GITHUB_OUTPUT
+        echo "max=$max_version" >> $GITHUB_OUTPUT
+  mike-version:
+    runs-on: ubuntu-latest
+    needs: [ set-versions]
+    outputs:
+      mver: ${{ steps.versions.mver }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ needs.set-versions.outputs.max }}
+      uses: actions/setup-python@v5
+      # This is deliberately not using a custom credential as it relies on native github actions token to have push rights.
+      with:
+        python-version: ${{ needs.set-versions.outputs.max }}
+    - id: versions
+      run: |
+        mike_version=$(python ./scripts/check-version.py ${{ env.GITHUB_REF }})
+        echo "mver=$mike_version" >> $GITHUB_OUTPUT
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: [ mike-version ]
+    steps:
+    - uses: actions/create-github-app-token@v1
+      id: app-token
+      with:
+        app-id: ${{ secrets.APP_ID }}
+        private-key: ${{ secrets.PRIVATE_KEY }}
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+        token: ${{ steps.app-token.outputs.token }}
+    - name: Set up Python ${{ needs.set-versions.outputs.max }}
+      uses: actions/setup-python@v5
+      # This is deliberately not using a custom credential as it relies on native github actions token to have push rights.
+      with:
+        python-version: ${{ needs.set-versions.outputs.max }}
+    - name: Install build tools
+      run: |
+        make develop
+    - name: Install documenation dependencies
+      run: |
+        make docs-ubuntu-deps
+    - name: Create release
+      shell: bash
+      run: |
+        mike deploy ${{ needs.mike-version.outputs.mver }}
+    - name: Ensure latest is latest
+      shell: bash
+      run: | 
+        mike set-default latest

.github/workflows/python-push.yml

@@ -153,41 +153,6 @@ jobs:
       with:
         github_token: ${{ steps.app-token.outputs.token }}
 
-  deploy-docs:
-    runs-on: ubuntu-latest
-    needs: [ deploy, set-versions ]
-    concurrency: 
-      group: ${{ github.ref }}-${{ github.workflow }}-${{ github.job }}-docs
-      cancel-in-progress: true
-    # Temporary hack: allow develop as well as master to deploy docs.
-    if: github.ref == 'refs/heads/main'
-    steps:
-    - uses: actions/create-github-app-token@v1
-      id: app-token
-      with:
-        app-id: ${{ secrets.APP_ID }}
-        private-key: ${{ secrets.PRIVATE_KEY }}
-    - uses: actions/checkout@v4
-      with:
-        submodules: true
-        fetch-depth: 0
-        token: ${{ steps.app-token.outputs.token }}
-    - name: Set up Python ${{ needs.set-versions.outputs.max }}
-      uses: actions/setup-python@v5
-      # This is deliberately not using a custom credential as it relies on native github actions token to have push rights.
-      with:
-        python-version: ${{ needs.set-versions.outputs.max }}
-    - name: Install build tools
-      run: |
-        make develop
-    - name: Install documenation dependencies
-      run: |
-        make docs-ubuntu-deps
-    - name: Create release
-      shell: bash
-      run: |
-        mkdocs gh-deploy
-
   merge-main-to-develop:
     name: Merge main -> develop
     runs-on: ubuntu-latest

mkdocs.yml

@@ -36,7 +36,7 @@ plugins:
     raise_error_excludes:
       # This is to remove some false positives for links which work.
       # Anchors are validated again by core mkdocs
-      404: ['#trestle.*']
+      404: [ '#trestle.*' ]
 - mkdocstrings:
     default_handler: python
     handlers:
@@ -61,6 +61,15 @@ plugins:
     - css/mkdocstrings.css
     htmlmin_opts:
       remove_comments: true
+- mike:
+    # These fields are all optional; the defaults are as below...
+    alias_type: symlink
+    redirect_template: null
+    deploy_prefix: ''
+    canonical_version: latest
+    version_selector: true
+    css_dir: css
+    javascript_dir: js
 repo_name: oscal-compass/compliance-trestle
 repo_url: https://github.com/oscal-compass/compliance-trestle
 site_description: Documentation for compliance-trestle package.

setup.cfg

@@ -79,6 +79,7 @@ dev =
     types-requests
     types-setuptools
     # # Docs website
+    mike
     mkdocs>=1.6.0
     mkdocs-awesome-pages-plugin
     mkdocstrings[python]>=0.25.2