Merges rcpch/digital-growth-charts-documentation site into the dGC server repo

.github/ISSUE_TEMPLATE/hazard-issue-template.md

@@ -0,0 +1,36 @@
+---
+name: "New Hazard Issue Template"
+about: "This template helps with creation of a new Hazard"
+title: "HAZARD: <hazard_name>"
+labels: new-hazard-for-triage, hazard
+assignees:
+---
+This Issue Template is based on the practices described in NHS Digital DCB0129/DCB0160 Clinical Safety Officer training.
+
+### Description
+A general description of the Hazard. Keep it short. Detail goes below.
+
+### Cause
+The upstream system Cause (can be multiple - use a numbered list) that results in the change to intended care.
+
+### Effect
+The change in the intended care pathway resulting from the Cause.
+
+### Hazard
+The *potential* for Harm to occur, even if it does not.
+
+### Harm
+An actual occurrence of a Hazard in the patient or clinical context. This is what we are assessing the **Severity** and **Likelihood** of.
+
+### Possible Causes
+An analysis of the Causes of the Hazard
+
+-----
+
+**Assignment**: Assign this Hazard to its Owner. Default owner is the Clinical Safety Officer @pacharanero
+**Labelling**: Add labels according to Severity. Likelihood and Risk Level
+**Project**: Add to the Project 'Clinical Risk Management'
+
+* Subsequent discussion can be used to mitigate the Hazard, reducing the likelihood (or less commonly reducing the severity) of the Harm.
+* If Harm is reduced then you can change the labels to reflect this and reclassify the Risk Score.
+* Issues can be linked to: Issues describing specific software changes, Pull Requests or Commits fixing Issues, external links, and much more supporting documentation. Aim for a comprehensive, well-evidenced, public and open discussion on risk and safety.

.github/labels.yml

@@ -0,0 +1,85 @@
+# This file contains definitions for the Hazard Log labels
+# Reference: DCB0129: Clinical Risk Management: its Application in the Manufacture of Health IT Systems
+# https://digital.nhs.uk/data-and-information/information-standards/information-standards-and-data-collections-including-extractions/publications-and-notifications/standards-and-collections/dcb0129-clinical-risk-management-its-application-in-the-manufacture-of-health-it-systems
+# Implementation Guidance https://digital.nhs.uk/binaries/content/assets/legacy/pdf/0129242018impguid.pdf
+# They are applied by the '.github/workflows/create-hazard-log-labels.yml' Action which is manually run
+
+
+# General Utility labels
+- name: "hazard"
+  description: "A hazard which is logged."
+  color: "892CBB"
+
+- name: "new-hazard-for-triage"
+  description: "A new hazard which needs to be triaged for severity and likelihood, scored and assigned."
+  color: "892CBB"
+
+- name: "deprecated-hazard"
+  description: "A hazard which is no longer considered relevant."
+  color: "892CBB"
+
+
+# Likelihood scoring
+- name: "likelihood-very-high"
+  description: "Certain or almost certain; highly likely to occur."
+  color: "C5D9F1"
+
+- name: "likelihood-high"
+  description: "Not certain but very possible; reasonably expected to occur in the majority of cases."
+  color: "C5D9F1"
+
+- name: "likelihood-medium"
+  description: "Possible."
+  color: "C5D9F1"
+
+- name: "likelihood-low"
+  description: "Could occur but in the great majority of occasions will not."
+  color: "C5D9F1"
+
+- name: "likelihood-very-low"
+  description: "Negligible or nearly negligible possibility of occurring."
+  color: "C5D9F1"
+
+
+# Severity scoring 
+- name: "severity-catastrophic"
+  description: "Death, 2+. Severe injury or lifechanging incapacity, 2+."
+  color: "D8E4BC"
+
+- name: "severity-major"
+  description: "Death, 1; Severe injury or life-changing incapacity, 1; Psychological trauma, 2+."
+  color: "D8E4BC"
+
+- name: "severity-considerable"
+  description: "Severe injury, 1, severe incapacity, recovery expected; Significant psych. trauma, 2+."
+  color: "D8E4BC"
+
+- name: "severity-significant"
+  description: "Minor injury, long term, 1; Significant psych. trauma, 1; Minor inj/psych trauma, 2+."
+  color: "D8E4BC"
+
+- name: "severity-minor"
+  description: "Minor injury, short term recovery; minor psychological upset; inconvenience; negligible consequence."
+  color: "D8E4BC"
+
+
+# Risk scoring
+- name: "risk-level-1-acceptable"
+  description: "Acceptable, no further action required"
+  color: "0E8A16"
+
+- name: "risk-level-2-acceptable"
+  description: "Acceptable if cost of further reduction > benefits, or further risk reduction is impractical"
+  color: "FBCA04"
+
+- name: "risk-level-3-undesirable"
+  description: "Undesirable level of risk. Attempts should be made to eliminate the hazard or implement controls"
+  color: "D93F0B"
+
+- name: "risk-level-4-mandatory-risk-elimination"
+  description: "Mandatory elimination of hazard or addition of controls to reduce risk to an acceptable level"
+  color: "ED5D40"
+
+- name: "risk-level-5-unacceptable"
+  description: "Unacceptable level of risk"
+  color: "B60205"

.github/workflows/all-branches-and-PRs-test.yml

@@ -18,10 +18,10 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4 # latest as at February 2024
+      - uses: actions/checkout@v4 # latest as at Apr 2024
 
       - name: Set up Python version ${{ matrix.python-version }}
-        uses: actions/setup-python@v5 # latest as at March 2024
+        uses: actions/setup-python@v5 # latest as at Apr 2024
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements/development-requirements.txt
+          pip install -r requirements.txt
 
       - name: Run pytest
         run: |

.github/workflows/auto-add-issues-to-project.yml

@@ -0,0 +1,20 @@
+name: Adds new Issues automatically to the dGC Project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add issue or PR to project automatically
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected] # latest as at April 2024
+        with:
+          project-url: https://github.com/orgs/rcpch/projects/5 #dGC Project
+          github-token: ${{ secrets.AUTO_ADD_TO_PROJECT_TOKEN }}
+

.github/workflows/create-hazard-log-labels.yml

@@ -0,0 +1,23 @@
+# Uses https://github.com/crazy-max/ghaction-github-labeler
+# Manually run the Action in the GitHub UI to add Hazard Log Labels as per the YAML file
+
+name: create-hazard-log-labels
+
+on:
+  workflow_dispatch
+
+jobs:
+  labeler:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4 # Latest as at April 2024
+      - name: Run Labeller
+        if: success()
+        uses: crazy-max/ghaction-github-labeler@v5 # Latest as at April 2024
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          yaml-file: .github/labels.yml
+          skip-delete: true # won't delete your existing labels
+          dry-run: false
+          exclude: 

.github/workflows/docs-all-PRs-build-deploy-to-azure.yml

@@ -0,0 +1,68 @@
+# This Action builds the documentation site in mkdocs
+# and pushes it to Azure from where it is deployed
+# to the LIVE site https://growth.rcpch.ac.uk/
+#
+# Azure will also build a preview site for any branches and any PRs against `live`.
+
+name: ALL-BRANCHES-ALL-PRs-build-and-deploy-to-azure.yml
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    branches:
+      - live
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write # this permission is required in order to allow PR comment with staging URL
+jobs:
+  build_and_deploy_job:
+    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
+    runs-on: ubuntu-latest
+    env:
+      ENABLE_PDF_EXPORT: 1 # Makes PDF export an option, default disabled, when building locally
+      ENABLE_GIT_COMMITTERS: True # Makes git-committers an option, default disabled, when building locally
+    name: Build and Deploy to Azure
+    steps:
+      - uses: actions/checkout@v4 # latest as at Apr 2024
+        with:
+          fetch-depth: 0 # required for git-revision and git-committers plugins to work properly in CI
+          submodules: true
+      - uses: actions/setup-python@v5 # latest as at Apr 2024
+        with:
+          python-version: '3.12'
+      - run: pip install -r documentation/docs-requirements.txt 
+      - run: cd documentation && mkdocs build
+      - name: Upload to Azure
+        id: builddeploy
+        uses: Azure/static-web-apps-deploy@v1 # latest as at Apr 2024
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_GLACIER_063C32703 }}
+          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
+          action: "upload"
+          production_branch: "live"
+          ###### Repository/Build Configurations ######
+          app_location: "" # App source code path relative to repository root
+          api_location: "" # Api source code path relative to repository root - optional
+          output_location: "documentation/site" # Built app content directory, relative to app_location - optional
+          ###### End of Repository/Build Configurations ######
+
+  # Deletes temporary deployment on Azure when PR is closed, therefore no longer needed.
+  close_pull_request_job:
+    if: github.event_name == 'pull_request' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    name: Close Pull Request Job
+    steps:
+      - name: Close Pull Request
+        id: closepullrequest
+        uses: Azure/static-web-apps-deploy@v1 # latest as at Apr 2024
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_GLACIER_063C32703 }}
+          action: "close"
+
+
+
+

.github/workflows/on-issue-labelled-hazard-reply-with-hazard-instructions.yml

@@ -0,0 +1,21 @@
+name: on-issue-labelled-hazard-reply-with-hazard-instructions
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  add-comment:
+    if: github.event.label.name == 'hazard'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Add comment
+        uses: peter-evans/create-or-update-comment@v4 # Latest as at April 2024
+        with:
+          issue-number: ${{ github.event.issue.number }}
+          body: |
+            Thank you for opening or editing a Hazard in the Hazard Log.
+            ### Next steps:
+            * Please use the Labels feature in the right sidebar area to stratify this Hazard in terms of **Likelihood** and **Severity**
+            * Assign the Issue to the Clinical Safety Officer for triage

.github/workflows/live_rcpch-dgc-server-live.yml → .github/workflows/rcpch-dgc-server-live-deploy-to-azure.yml

@@ -15,10 +15,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4 # latest as at March 2024
+      - uses: actions/checkout@v4 # latest as at April 2024
 
       - name: Set up Python version
-        uses: actions/setup-python@v5 # latest as at March 2024
+        uses: actions/setup-python@v5 # latest as at April 2024
         with:
           python-version: '3.12'
 

.github/workflows/staging_rcpch-dgc-server-staging.yml → .github/workflows/rcpch-dgc-server-staging-deploy-to-azure.yml

@@ -15,10 +15,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4 # latest as at March 2024
+      - uses: actions/checkout@v4 # latest as at April 2024
 
       - name: Set up Python version
-        uses: actions/setup-python@v5 # latest as at March 2024
+        uses: actions/setup-python@v5 # latest as at April 2024
         with:
           python-version: '3.12'
 
@@ -36,7 +36,7 @@ jobs:
         run: zip release.zip ./* -r
 
       - name: Upload artifact for deployment jobs
-        uses: actions/upload-artifact@v4 # latest as at March 2024
+        uses: actions/upload-artifact@v4 # latest as at April 2024
         with:
           name: python-app
           path: |

.gitignore

@@ -1,3 +1,7 @@
+site/
+.cache/
+
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Dockerfile

@@ -1,15 +1,24 @@
+# Dockerfile to build image for both FastAPI server and MkDocs documentation containers
 FROM python:3.12-bookworm
 
-COPY requirements/common-requirements.txt .
+# Extra packages required for Material for MkDocs plugins (dependency for git and pdf plugins)
+RUN apt-get update \
+    && apt install -y git python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0
 
-COPY requirements/development-requirements.txt .
+# Add FastAPI Server requirements
+COPY requirements.txt .
+RUN pip install -r requirements.txt
 
-RUN pip install -r development-requirements.txt
+# Add MkDocs requirements
+COPY documentation/docs-requirements.txt .
+RUN pip install -r docs-requirements.txt
 
 EXPOSE 8000
 
+# Set current working directory to /app
 WORKDIR /app
 
+# Copy codebase into /app
 COPY . /app
 
 CMD ["uvicorn", "main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

@@ -1,10 +1,22 @@
-# NOTE The below is the Docker Compose specification version NOT the Python version:
-version: "3.8"
+# This is a Docker Compose file for local development of the Digital Growth Charts Server and documentation.
+# version: 3.8 (Docker Compose version is now deprecated and no longer needed)
 
 services:
-  growth-api:
+  fastapi: # Digital Growth Charts Server
     build: .
     volumes:
       - .:/app
     ports:
-      - "8000:8000"
+      - "8000:8000" # FastAPI will be accessible at localhost:8000
+    restart: always
+
+  mkdocs: # Digital Growth Charts Documentation
+    build: .
+    volumes:
+      - .:/app # Copying entire directory contents (instead of just documentation/) because of issues related to .git directory (we are using some Git related MkDocs plugins - committers, history etc)
+    ports:
+      - 8001:8000 # MkDocs will be accessible at localhost:8001
+    command: >
+      sh -c "cd documentation && mkdocs build --config-file mkdocs.yml &&
+             mkdocs serve --dev-addr=0.0.0.0:8000 --config-file mkdocs.yml"
+    restart: always