Update documentation to use mkdocs

.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: Build and publish docs
+on:
+  push:
+    branches:
+      - main
+      - add-docs
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - name: Install Poetry
+        run: |
+          pip install -U pip
+          pip install poetry
+          poetry config virtualenvs.create false
+          poetry install --with docs
+      - run: poetry run mkdocs gh-deploy --force

.gitignore

@@ -5,6 +5,7 @@
 *.retry
 .env
 .envrc
+.cache
 *~
 /logs
 /data

Makefile

@@ -59,6 +59,7 @@ help:
 	@echo "$(CLR_Y)create_section_homepages$(CLR__) : Create the section homepages"
 	@echo "$(CLR_Y)setup_v2_user --email=someone@example.com$(CLR__) : Create/enable Django user with v2 search flag"
 	@echo "$(CLR_Y)data-countries$(CLR__) : Import the countries data"
+	@echo -e "$(COLOUR_YELLOW)make serve-docs$(COLOUR_NONE) : Serve mkdocs on port 8002"
 
 #
 # Makefile variables
@@ -268,3 +269,6 @@ data-countries:
 
 ingest-uk-staff-locations:
 	$(wagtail) python manage.py ingest_uk_staff_locations
+
+serve-docs:
+	poetry run mkdocs serve -a localhost:8002

docs/contributing/index.md

@@ -0,0 +1,16 @@
+# Contributing
+
+## Branch naming
+
+Branches should be named using the following format:
+`<Jira issue number>-<short description of change>`
+
+For example:
+`DWPF-123-update-readme`
+
+## Code style/formatting
+
+You can use the following commands to check and fix the code style/formatting:
+
+- Check the code: `make check`
+- Fix the code: `make fix`

docs/contributing/pull-requests.md

@@ -0,0 +1,26 @@
+# Pull requests
+
+## Naming
+
+Pull requests should be named using the following format:
+`<Jira issue number> <Short description of change>`
+
+For example:
+`DWPF-123 Update README.md`
+
+## Reviewing
+
+Pull requests have to be reviewed before they can be merged into `main`. The code should be reviewed by at least one other developer. To help the reviewer, include anything that might be helpful on the PR, things like screenshots of the changes and links to the dev environment.
+
+Make sure you don't include personal/sensitive information in the screenshots.
+
+## Merging
+
+PRs should only be merged once their contents can be considered "production ready". This means that the PR has been reviewed (as stated above) and that the code has been deployed to the dev environment and tested.
+
+Pull requests should be merged using the "Squash and merge" option. This will squash all commits into a single commit and will automatically close the PR. The commit message should contain the Jira issue number if it came from a Jira issue, a short description of the change and finally the PR number. For example:
+`DWPF-123 Update README.md (#45)`
+
+Once the PR has been merged, the branch should be deleted.
+
+Code deployed to `main` will be automatically deployed to the staging environment.

docs/contributing/releasing.md

@@ -0,0 +1,33 @@
+# Releasing
+
+Releases are done using the GitHub releases feature.
+
+- Go to the [releases page](https://github.com/uktrade/digital-workspace-v2/releases) and click the "Draft a new release" button.
+- At the top of the page click "Choose a tag" and create a new tag using the following format: `YYYY-MM.N` where `YYYY` is the current year, `MM` is the current month and `N` is the next release number.
+  - For example if the date is Sept 2023 and this is the first release of this month the tag would be: `2023-09.1`
+- Now, simply press the "Generate release notes" and review the release notes.
+  - You can share these notes with the team to ensure that they are happy with the release.
+- Finally, press the "Publish release" button. This will trigger a deployment to the production environment.
+
+## Release checklist
+
+When upgrading wagtail, check the:
+
+- front page
+  - news showing
+- content search
+- people finder search
+- people finder
+  - view profile
+  - edit profile
+  - view team
+  - edit team
+- django admin
+- wagtail admin
+  - home news order
+    - drag to sort
+  - add a news page
+    - upload and add an image
+    - publish and view live
+    - appears on home page
+    - appears on news page

docs/testing.md → docs/contributing/testing.md

@@ -1,5 +1,10 @@
 # Testing
 
+## Test commands
+
+- `make test`
+- `make test-e2e`
+
 ## E2E codegen tests
 
 When writing playwright tests it might be useful to use the `make e2e-codegen` tool to help generate code.

docs/features/index.md

@@ -0,0 +1,4 @@
+# Features
+
+This area of the documentation should be used to provide extra detail to some of the more complex features of the project.
+

docs/search.md → docs/features/search.md

@@ -1,4 +1,11 @@
-# How search works
+---
+hide:
+  - navigation
+---
+
+# Search
+
+## How search works
 
 Search is handled by [OpenSearch](https://opensearch.org/), an [ElasticSearch](https://www.elastic.co/) clone that runs as a service on AWS. Indexing and querying is managed by an extension to [Wagtail's in-built search](https://docs.wagtail.org/en/stable/topics/search/index.html) functionality.
 

docs/index.md

@@ -0,0 +1,6 @@
+---
+hide:
+  - navigation
+---
+
+# Digital Workspace

docs/js/tablesort.js

@@ -0,0 +1,6 @@
+document$.subscribe(function() {
+    var tables = document.querySelectorAll("article table:not([class])")
+    tables.forEach(function(table) {
+        new Tablesort(table);
+    });
+});

mkdocs.yml

@@ -0,0 +1,71 @@
+# Project specific config:
+site_name: Digital Workspace docs
+site_url: https://github.com/uktrade/digital-workspace-v2
+repo_name: uktrade/digital-workspace-v2
+repo_url: https://github.com/uktrade/digital-workspace-v2
+site_description: Documentation for the Digital Workspace Service
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/uktrade/digital-workspace-v2/
+
+# Standard config:
+plugins:
+  - awesome-pages
+  - material/social:
+      cards_color:
+        fill: "#ffffff"
+        text: "#000000"
+      cards_font: "Roboto"
+  - material/search:
+      lang: en
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+
+theme:
+  name: material
+  language: en
+  features:
+    - content.code.copy
+    - header.autohide
+    - navigation.indexes
+    - navigation.instant
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+  # logo: assets/dit-logo.png
+  favicon: assets/dit-favicon.png
+
+extra_javascript:
+  - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js # /PS-IGNORE
+  - js/tablesort.js
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      linenums: null
+      anchor_linenums: true
+      use_pygments: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - tables
+
+dev_addr: "127.0.0.1:8002"