create and publish the docuemntation pages

See #31

@edwardtheharris - [email protected]

Xander Harris

Changelog: changed

.github/workflows/pages.yml

@@ -0,0 +1,134 @@
+###
+# ```{rubric} MarkdownLint GitHub Actions
+# ```
+# ---
+# This is a basic workflow to help you get started with Actions.
+#
+# ```{literalinclude} /.github/workflows/pages.yml
+# :language: yaml
+# :start-at: "name: Test, Build, Deploy to GitHub Pages\n"
+# :end-before: "###\n"
+# ```
+#
+# Set a name for the workflow.
+name: Test, Build, Deploy to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch: {}
+
+###
+# ```{rubric} Permissions Updates
+# ```
+# Enable read for contents and issues, and write for checks and PRs.
+#
+# ```{literalinclude} /.github/workflows/pages.yml
+# :language: yaml
+# :start-at: "permissions:\n"
+# :end-before: "###\n"
+# ```
+permissions:
+  contents: read
+  issues: read
+  checks: write
+  pull-requests: write
+
+###
+# ```{rubric} Workflow Jobs
+# ```
+# ---
+# A workflow run is made up of one or more
+# jobs that can run sequentially or in parallel
+#
+jobs:
+  ###
+  # ```{rubric} markdownlint
+  # ```
+  # ---
+  # Check that the markdown in this repo is up to our (arbitrary) standards.
+  #
+  # ```{literalinclude} /.github/workflows/pages.yml
+  # :language: yaml
+  # :start-at: "markdownlint:\n"
+  # :end-before: "###\n"
+  # ```
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@main
+      - name: Set up NodeJS
+        uses: actions/setup-node@main
+      - name: Install the checker
+        run: npm i -g markdownlint-cli2 markdownlint-cli2-formatter-junit --save-dev
+      - name: Lint the Markdown
+        run: markdownlint-cli2 **/*.md
+      - name: Publish Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: markdownlint-cli2-junit.xml
+  ###
+  # ```{rubric} Build GitHub Pages Site
+  # ```
+  # ---
+  # Build the pages site using Sphinx and upload the resulting artifact.
+  #
+  # ```{literalinclude} /.github/workflows/pages.yml
+  # :language: yaml
+  # :start-at: "  build:\n"
+  # :end-before: "###\n"
+  # ```
+  build:
+    needs: markdownlint
+    runs-on: ubuntu-20.04
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@main
+      - uses: actions/setup-python@main
+        with:
+          python-version: 3.11
+          cache: pipenv
+      - name: Setup pages
+        uses: actions/configure-pages@main
+      - name: Install pipenv
+        run: curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
+      - name: Install Python dependencies
+        run: pipenv install
+      - name: Build the static site
+        run: pipenv run sphinx-build -a -E . deploy
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@main
+        with:
+          path: './deploy'
+  ###
+  # ```{rubric} Deploy the Pages site
+  # ```
+  # ---
+  # Download the artifact and deploy to pages.
+  #
+  # ```{literalinclude} /.github/workflows/pages.yml
+  # :language: yaml
+  # :start-at: "  pages:\n"
+  # ```
+  pages:
+    needs: build
+    runs-on: ubuntu-20.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Download pages artifact
+        id: download
+        uses: actions/download-artifact@main
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4