chore: add mdformat hook and update formatting of Markdown files

Author: mschoettle

.gitlab/merge_request_templates/Default.md

@@ -1,8 +1,8 @@
 **By submitting this merge request, I confirm the following:** _please fill any appropriate checkboxes, e.g: [x]_
 
-* [ ] The merge request title follows the conventional commits convention
-* [ ] I have self-reviewed my changes before requesting a review.
-* [ ] I have made only one major change in my proposed changes.
+- [ ] The merge request title follows the conventional commits convention
+- [ ] I have self-reviewed my changes before requesting a review.
+- [ ] I have made only one major change in my proposed changes.
 
 ## Description
 

.pre-commit-config.yaml

@@ -27,6 +27,15 @@ repos:
       - id: detect-private-key
       - id: end-of-file-fixer
 
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+        language: python
+        additional_dependencies:
+          - mdformat-mkdocs==4.1.2
+          - mdformat-footnote==0.1.1
+
   - repo: https://github.com/DavidAnson/markdownlint-cli2
     rev: v0.17.2
     hooks:

CHANGELOG.md

@@ -13,10 +13,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
-* Add Code Review Guidelines (!2)
+- Add Code Review Guidelines (!2)
 
 ## [Initial version]
 
-* Add software versions in use at O-HIG
-* Add Software Engineering related documentation (migrated from Google Docs)
-* **NEW**: Initial release.
+- Add software versions in use at O-HIG
+- Add Software Engineering related documentation (migrated from Google Docs)
+- **NEW**: Initial release.

README.md

@@ -23,9 +23,9 @@ All documentation is written in Markdown and located in the `docs/` directory.
 
 The documentation is split into several parts:
 
-* `user` contains the user guide
-* `development` contains information about contributing to Opal
-* `deploy` contains information about how to deploy and run Opal, and how to integrate the Opal services with a hospital
+- `user` contains the user guide
+- `development` contains information about contributing to Opal
+- `deploy` contains information about how to deploy and run Opal, and how to integrate the Opal services with a hospital
 
 ### Getting started
 
@@ -64,7 +64,7 @@ We also enforce [semantic line breaks](https://sembr.org).
 This makes it easier to read in source and also easier to review changes to the text.
 
 **Note:** This is an additional rule for `markdownlint`.
-    Due to a [limitation](https://github.com/DavidAnson/vscode-markdownlint/issues/336) with the vscode extension this rule is currently only enabled in CI.
+Due to a [limitation](https://github.com/DavidAnson/vscode-markdownlint/issues/336) with the vscode extension this rule is currently only enabled in CI.
 
 ### Adding a new page
 

docs/changelog.md

@@ -5,4 +5,5 @@ SPDX-License-Identifier: MIT
 -->
 
 <!-- markdownlint-disable first-line-h1 -->
+
 --8<-- "CHANGELOG.md"

docs/deploy/integration.md

@@ -12,10 +12,10 @@ In addition, hospitals must provide some endpoints to Opal in order to facilitat
 Opal source data APIs are provided by four subcomponents within the application layer.
 Those are:
 
-* [Backend](https://gitlab.com/opalmedapps/backend)
-* [OpalAdmin](https://gitlab.com/opalmedapps/opalAdmin)
-* [Opal-Labs](https://gitlab.com/opalmedapps/opal-labs)
-* [ORMS](https://gitlab.com/opalmedapps/ORMS)  *If wait room support is enabled at hospital*
+- [Backend](https://gitlab.com/opalmedapps/backend)
+- [OpalAdmin](https://gitlab.com/opalmedapps/opalAdmin)
+- [Opal-Labs](https://gitlab.com/opalmedapps/opal-labs)
+- [ORMS](https://gitlab.com/opalmedapps/ORMS) *If wait room support is enabled at hospital*
 
 In order to successfully integrate the Opal solution with a hospital data system, the above mentioned application container images must be deployed to an application server and configured with database access, SSL certificates, and environment configuration.
 
@@ -95,8 +95,8 @@ Opal-RMS separates private from public APIs and thus any calls to the public API
 
 In general the expectation for all Opal API is that payloads and responses are transmitted in JSON format, with a few exceptions.
 
-* As an experimental feature, the pharmacy data endpoint within the Opal-backend (`/api/patients/${uuid}/pharmacy`) was created with a built-in HL7 parsing class, the accepted data format is `application/hl7v2+er7`.
-* In the `Requirements for Hospital Endpoints` section (see below), the sending of patient weight measurement PDFs from the wait room management system is expected to be sent with XML data containing a base64 string encoding of the measurement PDF.
+- As an experimental feature, the pharmacy data endpoint within the Opal-backend (`/api/patients/${uuid}/pharmacy`) was created with a built-in HL7 parsing class, the accepted data format is `application/hl7v2+er7`.
+- In the `Requirements for Hospital Endpoints` section (see below), the sending of patient weight measurement PDFs from the wait room management system is expected to be sent with XML data containing a base64 string encoding of the measurement PDF.
 
 ## OpenAPI Schemas for Opal Source Data
 
@@ -105,10 +105,10 @@ For the `Opal-Backend`, we use [drf-spectacular](https://pypi.org/project/drf-sp
 This swagger page is accessible for authenticated users via `/api/schema/swagger-ui`.
 For convenience, all endpoints in all openapi specifications related to integrations have been tagged with the `institution integration` label within the openapi specification.
 
-* Opal-Backend: Swagger rendering at {hostAddress}/api/schema/swagger-ui
-* [Opal-Admin: openapi.yml](https://gitlab.com/opalmedapps/opalAdmin/-/blob/develop/php/openapi.yml?ref_type=heads)
-* [Opal-Labs: openapi.yml](https://gitlab.com/opalmedapps/opal-labs/-/blob/main/openapi.yml?ref_type=heads)
-* [Opal-RMS: openapi.yml](https://gitlab.com/opalmedapps/ORMS/-/blob/dev/php/api/public/v1/openapi.yml?ref_type=heads)
+- Opal-Backend: Swagger rendering at {hostAddress}/api/schema/swagger-ui
+- [Opal-Admin: openapi.yml](https://gitlab.com/opalmedapps/opalAdmin/-/blob/develop/php/openapi.yml?ref_type=heads)
+- [Opal-Labs: openapi.yml](https://gitlab.com/opalmedapps/opal-labs/-/blob/main/openapi.yml?ref_type=heads)
+- [Opal-RMS: openapi.yml](https://gitlab.com/opalmedapps/ORMS/-/blob/dev/php/api/public/v1/openapi.yml?ref_type=heads)
 
 ## Requirements for Hospital Endpoints
 

docs/development/architecture/index.md

@@ -10,9 +10,10 @@ Opal is a solution aimed at providing patients and their caregivers[^1] access t
 Opal provides two main parts to achieve this goal:
 
 1. A patient/caregiver-facing part to give them access to the medical data.
-2. A clinical staff facing part to manage the patient data.
+1. A clinical staff facing part to manage the patient data.
 
 !!! note
+
     The diagrams presented here are based on the [C4 model](https://c4model.com) for visualizing software architecture.
     They are created with [PlantUML](https://plantuml.com) using the [C4 PlantUML Extension](https://github.com/plantuml-stdlib/C4-PlantUML).
 
@@ -72,8 +73,8 @@ The following is an overview of all the components that are part of the Opal sol
 
 ### Opal Integration Engine (OIE)
 
-* [Project Page](https://gitlab.com/opalmedapps/opal-integration-engine)
-* [Mirth Connect](https://www.nextgen.com/solutions/interoperability/mirth-integration-engine)
+- [Project Page](https://gitlab.com/opalmedapps/opal-integration-engine)
+- [Mirth Connect](https://www.nextgen.com/solutions/interoperability/mirth-integration-engine)
 
 The OIE is responsible for interfacing with the hospital's interface.
 It receives unsolicited HL7 messages from hospital source systems.
@@ -91,7 +92,7 @@ For the latter case, the OIE provides a set of API endpoints for our components
 
 ### OpalAdmin
 
-* [Project Page](https://gitlab.com/opalmedapps/OpalAdmin)
+- [Project Page](https://gitlab.com/opalmedapps/OpalAdmin)
 
 OpalAdmin provides the admin interface for clinicians and staff.
 The web application is used to manage patients, hospital maps, questionnaires etc.
@@ -104,24 +105,24 @@ These scripts manage new data that was added, and determine whether caregivers n
 
 ### Listener
 
-* [Project Page](https://gitlab.com/opalmedapps/opal-listener)
-* [Published Documentation](https://opalmedapps.gitlab.io/opal-listener)
+- [Project Page](https://gitlab.com/opalmedapps/opal-listener)
+- [Published Documentation](https://opalmedapps.gitlab.io/opal-listener)
 
 The listener is the component that interacts with Firebase in order to handle requests coming from the user applications.
 The requests it handles are those intended for the hospital the Opal PIE is operating in.
 See the [section on communication below](#communication-between-user-applications-and-the-opal-pie) for more information.
 
 The listener contains legacy app and registration functionality as well as new functionality for forwarding API requests to the backend:
 
-* The legacy part handles request types and directly executes queries on the databases.
-* The new functionality receives API requests (basically, HTTP requests as JSON) and forwards them to the backend API.
-  It acts as a kind of proxy/middleware and makes actual HTTP requests.
-  The HTTP response is returned.
+- The legacy part handles request types and directly executes queries on the databases.
+- The new functionality receives API requests (basically, HTTP requests as JSON) and forwards them to the backend API.
+    It acts as a kind of proxy/middleware and makes actual HTTP requests.
+    The HTTP response is returned.
 
 ### Backend
 
-* [Project Page](https://gitlab.com/opalmedapps/backend)
-* [Published Documentation](https://opalmedapps.gitlab.io/backend)
+- [Project Page](https://gitlab.com/opalmedapps/backend)
+- [Published Documentation](https://opalmedapps.gitlab.io/backend)
 
 The backend (aka. _New OpalAdmin_) is the new backend that replaces the [legacy OpalAdmin](#opaladmin).
 It provides APIs for the user applications and other systems, such as the OIE.
@@ -131,7 +132,7 @@ Over time, other existing functionality will be migrated to this component (see
 
 ### Opal Labs
 
-* [Project Page](https://gitlab.com/opalmedapps/opal-labs)
+- [Project Page](https://gitlab.com/opalmedapps/opal-labs)
 
 _Opal Labs_ is an additional component which takes care of processing new lab results for patients.
 It exposes an API endpoint for use by the OIE to handle new lab results.
@@ -147,8 +148,8 @@ It also makes an API call to _OpalAdmin_ to request sending a push notification
 
 ### User Registration
 
-* [Project Page](https://gitlab.com/opalmedapps/registration-web-page)
-* [Production Registration](https://registration.opalmedapps.ca)
+- [Project Page](https://gitlab.com/opalmedapps/registration-web-page)
+- [Production Registration](https://registration.opalmedapps.ca)
 
 The registration websites provides a user (caregiver) the ability to create their Opal account.
 In order to use the registration website, a caregiver has to request access to a patient's data at the hospital.
@@ -157,7 +158,7 @@ Using the registration code and the patient's identification number (RAMQ or MRN
 
 ### Web and Mobile App
 
-* [Project Page](https://gitlab.com/opalmedapps/qplus)
+- [Project Page](https://gitlab.com/opalmedapps/qplus)
 
 The web and mobile app provide caregivers the ability to access patient data for the patients under their care.
 The mobile app is the same as the web app.
@@ -168,7 +169,7 @@ The mobile app supports additional features native to mobile devices, such as lo
 
 #### Database Migrations and Initial Data
 
-* [Project Page](https://gitlab.com/opalmedapps/db-docker/)
+- [Project Page](https://gitlab.com/opalmedapps/db-docker/)
 
 Historically, the legacy components of Opal did not maintain migrations of the database schema.
 Migrations and initial data (to set up Opal at a new hospital) is maintained in this separate component.
@@ -182,7 +183,7 @@ It is only necessary to run this during setup and upgrade.
 
 #### Redis
 
-* [Project Page](https://redis.io/)
+- [Project Page](https://redis.io/)
 
 Redis is used by _Opal Labs_ to cache patients being processed to avoid sending caregivers multiple push notification times when batch processing.
 
@@ -193,8 +194,8 @@ Firebase is used to support passing data from within the hospital firewall to th
 
 Opal makes use of two Firebase services:
 
-* [_Authentication_](https://firebase.google.com/docs/auth) is used for user accounts (via email and password).
-* [_Realtime Database_](https://firebase.google.com/docs/database) is used to pass requests and responses between user applications and the Opal PIE.
+- [_Authentication_](https://firebase.google.com/docs/auth) is used for user accounts (via email and password).
+- [_Realtime Database_](https://firebase.google.com/docs/database) is used to pass requests and responses between user applications and the Opal PIE.
 
 A Firebase user account is created when a user completes the user registration for the first time.
 The Firebase Realtime Database acts as a kind of queue for sending requests and receiving responses.
@@ -213,10 +214,6 @@ TBC
 
 https://gitlab.com/opalmedapps/qplus
 
-[^1]:
-    We consider a caregiver to also include the patient.
-    In that case they are caring for themself.
-
 ### Appointment Checkin Processes
 
 A core functionality within the Opal ecosystem is the ability for a patient (or a caregiver of a patient) to checkin to an appointment at the hospital.
@@ -248,13 +245,16 @@ However, ORMs also provides several additional methods of checking in to an appo
 
 These are:
 
-* Kiosk Checkins - where a patient can scan their hospital card at an ORMs kiosk in the hospital to checkin to all appointments for the day, before proceeding to the waiting room
-* Virtual Waiting Room (VWR) Checkins - where a patient can request to be checked into all appointments for that day at a reception desk, and a clinical staff member uses the ORMs VWR to perform the checkin on the patient's behald
-* SMS Checkins - where a patient can respond to an automated SMS received to their mobile device with the phrase 'Check In' in order to be checked in for all appointments for the day
+- Kiosk Checkins - where a patient can scan their hospital card at an ORMs kiosk in the hospital to checkin to all appointments for the day, before proceeding to the waiting room
+- Virtual Waiting Room (VWR) Checkins - where a patient can request to be checked into all appointments for that day at a reception desk, and a clinical staff member uses the ORMs VWR to perform the checkin on the patient's behald
+- SMS Checkins - where a patient can respond to an automated SMS received to their mobile device with the phrase 'Check In' in order to be checked in for all appointments for the day
 
 From the perspective of the Opal ecosystem, all three of these checkin methods are identical in that they result in the same API call(s) from ORMs to Opal, although from a patient perspective they are different.
 
 The following sequence diagram details the series of API calls that are made immediately after a patient attempts a checkin from a wait room Kiosk, from their phone SMS, or via a clinical staff member interacting with the ORMs virtual waiting room.
 
 ```plantuml source="docs/development/architecture/diagrams/checkins/orms_checkins.puml"
 ```
+
+[^1]: We consider a caregiver to also include the patient.
+    In that case they are caring for themself.