Initial docs layout (draft)

.github/workflows/ci.yml

@@ -33,6 +33,23 @@ jobs:
       - pre-commit
     uses: ./.github/workflows/test-action.yml
 
+  docs:
+    name: Docs
+    needs:
+      - pre-commit
+    uses: ./.github/workflows/docs-action.yml
+
+  deploy-docs:
+    name: Deploy Docs
+    uses: ./.github/workflows/deploy-docs-action.yml
+    # Only build doc deployments from the main branch of the org repo and never for PRs.
+    if: >-
+      github.event_name != 'pull_request' &&
+      github.ref == 'refs/heads/main'
+    needs:
+      - docs
+      - test
+
   set-pipeline-exit-status:
     # This step is just so we can make github require this step, to pass checks
     # on a pull request instead of requiring all
@@ -41,29 +58,30 @@ jobs:
     if: always()
     needs:
       - test
+      - docs
     steps:
-    - name: Download Exit Status Files
-      if: always()
-      uses: actions/download-artifact@v4
-      with:
-        path: exitstatus
-        pattern: exitstatus-*
-        merge-multiple: true
+      - name: Download Exit Status Files
+        if: always()
+        uses: actions/download-artifact@v4
+        with:
+          path: exitstatus
+          pattern: exitstatus-*
+          merge-multiple: true
 
-    - name: Delete Exit Status Artifacts
-      if: always()
-      uses: geekyeggo/delete-artifact@v5
-      with:
-        name: exitstatus-*
-        useGlob: true
-        failOnError: false
+      - name: Delete Exit Status Artifacts
+        if: always()
+        uses: geekyeggo/delete-artifact@v5
+        with:
+          name: exitstatus-*
+          useGlob: true
+          failOnError: false
 
-    - name: Set Pipeline Exit Status
-      run: |
-        tree exitstatus
-        grep -RE 'failure|cancelled' exitstatus/ && exit 1 || exit 0
+      - name: Set Pipeline Exit Status
+        run: |
+          tree exitstatus
+          grep -RE 'failure|cancelled' exitstatus/ && exit 1 || exit 0
 
-    - name: Done
-      if: always()
-      run:
-        echo "All workflows finished"
+      - name: Done
+        if: always()
+        run:
+          echo "All workflows finished"

.github/workflows/deploy-docs-action.yml

@@ -0,0 +1,76 @@
+name: Publish Documentation
+
+on:
+  workflow_call:
+    inputs:
+      # This is the name of the regular artifact that should
+      # be transformed into a GitHub Pages deployment.
+      artifact-name:
+        type: string
+        required: false
+        default: html-docs
+
+jobs:
+
+  # The released docs are not versioned currently, only the latest ones are deployed.
+  #
+  # Versioning support would require either (better):
+  #   * Rebuilding docs for all versions when a new release is made
+  #   * Version selector support in `furo`: https://github.com/pradyunsg/furo/pull/500
+  #
+  # or (more basic):
+  #   * using the `gh-pages` branch and peaceiris/actions-gh-pages
+  #     to be able to deploy to subdirectories. The implementation via
+  #     actions/deploy-pages always replaces the directory root.
+
+  Deploy-Docs-GH-Pages:
+    name: Publish Docs to GitHub Pages
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      pages: write
+      id-token: write
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download built docs
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name }}
+          path: html-docs
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          name: html-docs-pages
+          path: html-docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: html-docs-pages
+
+      - name: Delete GitHub Pages artifact
+        if: always()
+        uses: geekyeggo/delete-artifact@v5
+        with:
+          name: html-docs-pages
+          failOnError: false
+
+      - name: Set Exit Status
+        if: always()
+        run: |
+          mkdir exitstatus
+          echo "${{ job.status }}" > exitstatus/${{ github.job }}
+
+      - name: Upload Exit Status
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: exitstatus-${{ github.job }}
+          path: exitstatus
+          if-no-files-found: error

.github/workflows/docs-action.yml

@@ -0,0 +1,52 @@
+name: Build Documentation
+
+on:
+  workflow_call:
+
+jobs:
+  Docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12 For Nox
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Nox
+        run: |
+          python -m pip install --upgrade pip
+          pip install nox
+
+      - name: Install Doc Requirements
+        run: |
+          nox --force-color -e docs --install-only
+
+      - name: Build Docs
+        env:
+          SKIP_REQUIREMENTS_INSTALL: true
+        run: |
+          nox --force-color -e docs
+
+      - name: Upload built docs as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: docs/_build/html
+
+      - name: Set Exit Status
+        if: always()
+        run: |
+          mkdir exitstatus
+          echo "${{ job.status }}" > exitstatus/${{ github.job }}
+
+      - name: Upload Exit Status
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: exitstatus-${{ github.job }}
+          path: exitstatus
+          if-no-files-found: error

.github/workflows/pr.yml

@@ -14,4 +14,6 @@ jobs:
     uses: ./.github/workflows/ci.yml
     permissions:
       contents: write
+      pages: write
+      id-token: write
       pull-requests: read

CHANGELOG.md

@@ -0,0 +1,5 @@
+The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH
+
+# Changelog

changelog/.template.jinja

@@ -0,0 +1,15 @@
+{% if sections[""] %}
+{% for category, val in definitions.items() if category in sections[""] %}
+
+### {{ definitions[category]['name'] }}
+
+{% for text, values in sections[""][category].items() %}
+- {{ text }} {{ values|join(', ') }}
+{% endfor %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_ext/saltdomain.py

@@ -0,0 +1,18 @@
+"""
+Copied/distilled from Salt doc/_ext/saltdomain.py in order to be able
+to use Salt's custom doc refs.
+"""
+
+
+def setup(app):
+    app.add_crossref_type(
+        directivename="conf_master",
+        rolename="conf_master",
+        indextemplate="pair: %s; conf/master",
+    )
+    app.add_crossref_type(
+        directivename="conf_minion",
+        rolename="conf_minion",
+        indextemplate="pair: %s; conf/minion",
+    )
+    return {"parallel_read_safe": True, "parallel_write_safe": True}