Merge pull request #1 from ukgovdatascience/build-govuk-tech-docs-sph…

…inx-theme

Build GOV.UK Tech Docs Sphinx theme

.envrc

@@ -7,16 +7,16 @@
 #   EXAMPLE_VARIABLE = os.getenv("EXAMPLE_VARIABLE")
 #   --------------------------------------------------------
 #
-# To ensure the `sed` command below works correctly, make sure all file paths in environment variables are absolute,
-# are relative but do not reference any other variables except `$(pwd)`.
+# To ensure the `sed` command below works correctly, make sure all file paths in environment variables are absolute
+# (recommended), or are relative paths using other environment variables (works for Python users only). Environment
+# variable names are expected to contain letters, numbers or underscores only.
 #
 # DO NOT STORE SECRETS HERE - this file is version-controlled! You should store secrets in a `.secrets` file, which is
 # not version-controlled - this can then be sourced here, using `source_env ".secrets"`.
 
 # Extract the variables to `.env` if required. Note `.env` is NOT version-controlled, so `.secrets` will not be
-# committed. Use the first line if a `.secrets` file exists, otherwise use the second line
-# sed -n 's/^export \(.*\)$/\1/p' .envrc .secrets | sed -e 's?$(pwd)?'"$(pwd)"'?g' > .env
-sed -n 's/^export \(.*\)$/\1/p' .envrc | sed -e 's?$(pwd)?'"$(pwd)"'?g' > .env
+# committed
+sed -n 's/^export \(.*\)$/\1/p' .envrc | sed -e 's?$(pwd)?'"$(pwd)"'?g' | sed -e 's?$\([a-zA-Z0-9_]\{1,\}\)?${\1}?g' > .env
 
 # Add the working directory to PYTHONPATH
 export PYTHONPATH="$PYTHONPATH:$(pwd)"
@@ -27,5 +27,9 @@ export PYTHONPATH="$PYTHONPATH:$(pwd)"
 # Add environment variables for the `docs` directory
 export DIR_DOCS=$(pwd)/docs
 
+# Add environment variables for the `source` directories
+export DIR_SOURCE=$(pwd)/source
+export DIR_SOURCE_ALPHAGOV_TECH_DOCS_TEMPLATE=$(pwd)/source/alphagov-tech-docs-template
+
 # Add environment variables for the `tests` directory
 export DIR_TESTS=$(pwd)/tests

.flake8

@@ -5,4 +5,5 @@
 exclude = venv*,__pycache__,node_modules,bower_components,migrations
 ignore = D203,W503
 max-complexity = 9
-max-line-length = 120
+max-line-length = 88
+extend-ignore = E203

.github/pull_request_template.md

@@ -1,29 +1,31 @@
 # Summary
 
-Add your summary here - keep it brief, to the point, and in plain English. For further information about pull requests,
-check out the [GDS Way][gds-way].
+Add your summary here - keep it brief, to the point, and in plain English. [For further
+information about pull requests, check out the GDS
+Way](https://gds-way.cloudapps.digital/standards/pull-requests.html).
 
 # Checklists
 
 <!--
 These are DO-CONFIRM checklists; it CONFIRMs that you have DOne each item.
 
-Outstanding actions should be completed before reviewers are assigned; if actions are irrelevant, please try and add a
-comment stating why.
+Outstanding actions should be completed before reviewers are assigned; if actions are
+irrelevant, please try and add a comment stating why.
 
-Incomplete pull/merge requests MAY be blocked until actions are resolved, or closed at the reviewers' discretion.
+Incomplete pull/merge requests MAY be blocked until actions are resolved, or closed at
+the reviewers' discretion.
 -->
 
 This pull/merge request meets the following requirements:
 
 - [ ] Code runs
-- [ ] Developments are **secure** and [**ethical**][data-ethics-framework]
-- [ ] You have made proportionate checks that the code works correctly, and the theme works as expected
+- [ ] [Developments are ethical][data-ethics-framework] and secure
+- [ ] You have made proportionate checks that the code works correctly, and the theme
+  works as expected
 - [ ] Test suite passes
 - [ ] [Minimum usable documentation][agilemodeling] written in the `docs` folder
 
 Comments have been added below around the incomplete checks.
 
 [agilemodeling]: http://agilemodeling.com/essays/documentLate.htm
 [data-ethics-framework]: https://www.gov.uk/government/publications/data-ethics-framework
-[gds-way]: https://gds-way.cloudapps.digital/standards/pull-requests.html

.github/workflows/build.yml

@@ -0,0 +1,77 @@
+name: govuk-tech-docs-sphinx-theme build
+
+on: [ push, pull_request ]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        python: [ 3.6, 3.7, 3.8, 3.9 ]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install Poetry
+        uses: snok/install-poetry@v1.1.6
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+      - name: Load cached virtual environment
+        id: cached-poetry-dependencies
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+      - name: Install Poetry dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+      - name: Install library and dependencies
+        run: |
+          if [[ "$RUNNER_OS" == "Linux" || "$RUNNER_OS" == "macOS" ]]; then
+            poetry run make dependencies
+          elif [ "$RUNNER_OS" == "Windows" ]; then
+            poetry install --no-interaction
+            poetry run pre-commit install
+          else
+            echo "$RUNNER_OS not supported"
+            exit 1
+          fi;
+        shell: bash
+      - name: Run pre-commit hooks
+        run: poetry run pre-commit run --all-files
+      - name: Create documentation
+        run: |
+          source $VENV
+          if [[ "$RUNNER_OS" == "Linux" || "$RUNNER_OS" == "macOS" ]]; then
+            poetry run make docs
+          elif [ "$RUNNER_OS" == "Windows" ]; then
+            poetry run sphinx-build -b html ./docs ./docs/_build
+          else
+            echo "$RUNNER_OS not supported"
+            exit 1
+          fi;
+        shell: bash
+      - name: Execute tests, and create coverage report
+        run: |
+          source $VENV
+          if [[ "$RUNNER_OS" == "Linux" || "$RUNNER_OS" == "macOS" ]]; then
+            poetry run make coverage_xml
+          elif [ "$RUNNER_OS" == "Windows" ]; then
+            poetry run coverage run -m pytest
+            poetry run coverage xml
+          else
+            echo "$RUNNER_OS not supported"
+            exit 1
+          fi;
+        shell: bash
+      - name: Upload coverage report to Codecov
+        uses: codecov/codecov-action@v1
+        with:
+          files: ./coverage.xml
+          env_vars: OS=${{ matrix.os }},PYTHON=${{ matrix.python }}

.github/workflows/deploy-package-and-documentation.yml

@@ -0,0 +1,51 @@
+name: govuk-tech-docs-sphinx-theme deploy package and documentation
+
+on:
+  release:
+    types: [ released ]
+
+jobs:
+  deploy-package-and-documentation:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Install Poetry
+        uses: snok/install-poetry@v1.1.6
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+      - name: Load cached virtual environment
+        id: cached-poetry-dependencies
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+      - name: Install Poetry dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+      - name: Install dependencies
+        run: poetry run make dependencies
+      - name: Create documentation
+        run: poetry run make docs
+      - name: Build package
+        run: poetry build
+      - name: Set the deployment configuration for Poetry
+        run: poetry config pypi-token.pypi "$PYPI_API_TOKEN"
+        env:
+          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        shell: bash
+      - name: Publish to GitHub Pages
+        if: startsWith(github.ref, 'refs/tags')
+        uses: JamesIves/github-pages-deploy-action@4.1.4
+        with:
+          branch: gh-pages
+          folder: docs/_build
+      - name: Deploy package to PyPI
+        if: startsWith(github.ref, 'refs/tags')
+        run: poetry publish

.gitignore

@@ -856,5 +856,18 @@ MigrationBackup/
 
 ### GOV.UK Tech Docs Sphinx Theme ###
 
+# Ignore the contents of the `source` folder, except for the `README.md` file
+source/*
+!source/README.md
+
+# Ignore the contents of the `source` sub-folders, except for the `.template_version` file; adapted from
+# https://stackoverflow.com/a/20652768
+!source/**/
+source/alphagov-tech-docs-template/*
+!source/alphagov-tech-docs-template/.template_version
+
+# Ignore the `docs/reference/api` folder
+docs/reference/api/*
+
 # Ignore the `.secrets` file
 .secrets

.pre-commit-config.yaml

@@ -1,29 +1,38 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
--   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.4
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
     hooks:
-    -   id: flake8
-        args: ["govuk_tech_docs_sphinx_theme"]
--   repo: https://github.com/Yelp/detect-secrets
-    rev: v0.14.3
+      - id: check-added-large-files
+        name: Check for files larger than 5 MB
+        args: [ "--maxkb=5120" ]
+      - id: end-of-file-fixer
+        name: Check for a blank line at the end of scripts (auto-fixes)
+      - id: trailing-whitespace
+        name: Check for trailing whitespaces (auto-fixes)
+  - repo: https://github.com/pycqa/isort
+    rev: 5.8.0
     hooks:
-    -   id: detect-secrets
-        args: ["--baseline", ".secrets.baseline"]
-        exclude: .*/tests/.*
--   repo: https://github.com/aflc/pre-commit-jupyter
-    rev: v1.1.0
+      - id: isort
+        name: isort - Sort Python imports (auto-fixes)
+        types: [ cython, pyi, python ]
+        args: [ "--profile", "black", "--filter-files" ]
+  - repo: https://github.com/psf/black
+    rev: 21.5b2 # Replace by any tag/version: https://github.com/psf/black/tags
     hooks:
-    -   id: jupyter-notebook-cleanup
-        args:
-        -   --remove-kernel-metadata
-        -   --pin-patterns
-        -   "[keep_output]"
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.4.0
+      - id: black
+        name: black - consistent Python code formatting (auto-fixes)
+        language_version: python # Should be a command that runs python3.6+
+  - repo: https://gitlab.com/pycqa/flake8
+    rev: 3.9.2
     hooks:
-    -   id: check-added-large-files
-        args: ["--maxkb=5120"]
-    -   id: end-of-file-fixer
-    -   id: trailing-whitespace
+      - id: flake8
+        name: flake8 - Python linting
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.0.3
+    hooks:
+      - id: detect-secrets
+        name: detect-secrets - Detect secrets in staged code
+        args: [ "--baseline", ".secrets.baseline" ]
+        exclude: .*/tests/.*|^poetry\.lock$

.secrets.baseline

@@ -1,20 +1,18 @@
 {
-  "custom_plugin_paths": [],
-  "exclude": {
-    "files": null,
-    "lines": null
-  },
-  "generated_at": "2021-01-11T09:41:31Z",
+  "version": "1.0.3",
   "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
     {
       "name": "AWSKeyDetector"
     },
     {
-      "name": "ArtifactoryDetector"
+      "name": "AzureStorageKeyDetector"
     },
     {
-      "base64_limit": 4.5,
-      "name": "Base64HighEntropyString"
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
     },
     {
       "name": "BasicAuthDetector"
@@ -23,8 +21,8 @@
       "name": "CloudantDetector"
     },
     {
-      "hex_limit": 3,
-      "name": "HexHighEntropyString"
+      "name": "HexHighEntropyString",
+      "limit": 3.0
     },
     {
       "name": "IbmCloudIamDetector"
@@ -36,12 +34,15 @@
       "name": "JwtTokenDetector"
     },
     {
-      "keyword_exclude": null,
-      "name": "KeywordDetector"
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
     },
     {
       "name": "MailchimpDetector"
     },
+    {
+      "name": "NpmDetector"
+    },
     {
       "name": "PrivateKeyDetector"
     },
@@ -51,17 +52,43 @@
     {
       "name": "SoftlayerDetector"
     },
+    {
+      "name": "SquareOAuthDetector"
+    },
     {
       "name": "StripeDetector"
     },
     {
       "name": "TwilioKeyDetector"
     }
   ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
   "results": {},
-  "version": "0.14.3",
-  "word_list": {
-    "file": null,
-    "hash": null
-  }
+  "generated_at": "2021-06-17T14:10:18Z"
 }