Merge pull request #36 from edwardtheharris/31-create-and-publish-the…

…-docuemntation-pages

create and publish the docuemntation pages

Closes #31

.envrc

@@ -1,5 +1,10 @@
 #!/usr/local/bin/env bash
 
+if [ -f ~/.gnupg/github/sentry_dsn.gpg ]; then
+    SENTRY_DSN="$(gpg -d -q ~/.gnupg/github/sentry_dsn.gpg)"
+    export SENTRY_DSN
+fi
+
 PIPENV_VENV_IN_PROJECT=1
 
 export PIPENV_VENV_IN_PROJECT

.github/workflows/.bandit.txt

@@ -0,0 +1,84 @@
+###
+# ```{rubric} Bandit
+# ```
+# ---
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+#
+# Bandit is a security linter designed to find common security issues in Python code.
+# This action will run Bandit on your codebase.
+# The results of the scan will be found under the Security tab of your repository.
+#
+# [bandit-scan](https://github.com/marketplace/actions/bandit-scan) is ISC
+# licensed, by abirismyname
+# [bandit](https://pypi.org/project/bandit/) is Apache v2.0 licensed, by PyCQA
+#
+# ```{literalinclude} .github/workflows/bandit.yml
+# :language: yaml
+# :start-at: "name: Bandit\n"
+# :end-before: "###\n"
+# ```
+name: Bandit
+permissions:
+  contents: read
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    ###
+    # The branches below must be a subset of the branches above
+    branches: [ "main" ]
+  schedule:
+    - cron: '32 4 * * 4'
+###
+# ```{rubric} Bandit Jobs
+# ```
+# ---
+# Define the jobs necessary for a useful bandit run.
+#
+# ```{literalinclude} .github/workflows/bandit.yml
+# :language: yaml
+# :start-at: "jobs:\n"
+# ```
+jobs:
+  bandit:
+    permissions:
+      ###
+      # for actions/checkout to fetch code
+      contents: read
+      ###
+      # for github/codeql-action/upload-sarif to upload SARIF results
+      security-events: write
+      ###
+      # only required for a private repository by
+      # github/codeql-action/upload-sarif to get the Action run status
+      actions: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@main
+      - name: Bandit Scan
+        uses: shundor/python-bandit-scan@main
+        ###
+        # optional arguments
+        with:
+          ###
+          # exit with 0, even with results found
+          exit_zero: true # optional, default is DEFAULT
+          ###
+          # File or directory to run bandit on
+          # path: # optional, default is .
+          # Report only issues of a given severity level or higher. Can be LOW, MEDIUM or HIGH. Default is UNDEFINED (everything)
+          # level: # optional, default is UNDEFINED
+          # Report only issues of a given confidence level or higher. Can be LOW, MEDIUM or HIGH. Default is UNDEFINED (everything)
+          # confidence: # optional, default is UNDEFINED
+          # comma-separated list of paths (glob patterns supported) to exclude from scan (note that these are in addition to the excluded paths provided in the config file) (default: .svn,CVS,.bzr,.hg,.git,__pycache__,.tox,.eggs,*.egg)
+          # excluded_paths: # optional, default is DEFAULT
+          # comma-separated list of test IDs to skip
+          # skips: # optional, default is DEFAULT
+          # path to a .bandit file that supplies command line arguments
+          # ini_path: # optional, default is DEFAULT
+          # Github token of the repository (automatically created by Github)
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Needed to get PR information.
+

.github/workflows/.coveralls.txt

@@ -0,0 +1,42 @@
+on: ["push", "pull_request"]
+name: Test Coveralls
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    strategy:
+        matrix:
+          python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+    - uses: actions/checkout@main
+    - name: Setup Python
+      uses: actions/setup-python@main
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: git config
+      run: |
+        git config user.username edwardtheharris
+        git config user.name 'Xander Harris'
+        git config user.email '[email protected]'
+        git checkout -b 123-feature-branch-test
+    - name: Install Dependencies
+      run: |
+        pip3 install -U pip pipenv
+        pipenv requirements --dev > reqs
+        pip3 install -r reqs
+        pytest --cov
+    - name: Coveralls
+      uses: coverallsapp/github-action@v2
+      with:
+        parallel: true
+        flag-name: run-${{ matrix.python-version }}
+
+  finish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Close parallel build
+        uses: coverallsapp/github-action@v1
+        with:
+            parallel-finished: true
+            carryforward: "run-3.8,run-3.9,run-3.10,run-3.11,run-3.12"

.github/workflows/.ossar.txt

@@ -0,0 +1,87 @@
+###
+# ```{rubric} OSSAR
+# ```
+# ---
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+#
+# This workflow integrates a collection of open source static analysis tools
+# with GitHub code scanning. For documentation, or to provide feedback, visit
+# https://github.com/github/ossar-action
+#
+# ```{literalinclude} .github/workflows/ossar.yml
+# :language: yaml
+# :start-at: "name: OSSAR\n"
+# :end-before: "###\n"
+# ```
+name: OSSAR
+permissions:
+  contents: read
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    ###
+    # The branches below must be a subset of the branches above
+    branches: [ "main" ]
+  schedule:
+    - cron: '43 10 * * 4'
+###
+# ```{rubric} OSSAR Jobs
+# ```
+# ---
+# Define the jobs necessary for a useful ossar run.
+#
+# ```{literalinclude} .github/workflows/ossar.yml
+# :language: yaml
+# :start-at: "jobs:\n"
+# ```
+jobs:
+  OSSAR-Scan:
+    ###
+    # OSSAR runs on windows-latest.
+    # ubuntu-latest and macos-latest support coming soon
+    permissions:
+      ###
+      # for actions/checkout to fetch code
+      contents: read
+      ###
+      # for github/codeql-action/upload-sarif to upload SARIF results
+      security-events: write
+      ###
+      # only required for a private repository by
+      # github/codeql-action/upload-sarif to get the Action run status
+      actions: read
+    runs-on: windows-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@main
+    ###
+    # Ensure a compatible version of dotnet is installed.
+    # The [Microsoft Security Code Analysis CLI](https://aka.ms/mscadocs)
+    # is built with dotnet v3.1.201.
+    # A version greater than or equal to v3.1.201 of dotnet must be installed
+    # on the agent in order to run this action.
+    # GitHub hosted runners already have a compatible version of dotnet
+    # installed and this step may be skipped.
+    # For self-hosted runners, ensure dotnet version 3.1.201 or later is
+    # installed by including this action:
+    # ```{code-block} yaml
+    # - name: Install .NET
+    #   uses: actions/setup-dotnet@v2
+    #   with:
+    #     dotnet-version: '3.1.x'
+    # ```
+    #
+    # Run open source static analysis tools
+    - name: Run OSSAR
+      uses: github/ossar-action@main
+      id: ossar
+      ###
+      # Upload results to the Security tab
+    - name: Upload OSSAR results
+      uses: github/codeql-action/upload-sarif@main
+      with:
+        sarif_file: ${{ steps.ossar.outputs.sarifFile }}

.github/workflows/pages.yml

@@ -0,0 +1,136 @@
+###
+# ```{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 --categories docs
+          pipenv install -e .
+      - 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

.markdownlint-cli2.jsonc

@@ -0,0 +1,5 @@
+{
+  "outputFormatters": [
+    [ "markdownlint-cli2-formatter-junit" ]
+  ]
+}