Merge pull request #97 from rcpch/prerelease

Prerelease

Dockerfile

@@ -0,0 +1,28 @@
+# Base Docker image Official Python 3.10
+FROM python:3.11
+
+# Set 'build-time' environment variables
+ENV PYTHONDONTWRITEBYTECODE 1
+ENV PYTHONUNBUFFERED 1
+
+# 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
+
+# Add requirements
+COPY requirements.txt /app/requirements.txt
+
+# Set working directory for requirements installation
+WORKDIR /app/
+
+# Run installation of requirements
+RUN pip install --upgrade pip
+RUN pip install -r /app/requirements.txt
+
+# Set working directory back to main app
+WORKDIR /app/
+
+# Copy application code into image
+# (Excludes any files/dirs matched by patterns in .dockerignore)
+COPY . /app/
+

docs/_assets/_stylesheets/extra.css

@@ -32,6 +32,16 @@
 
 /* FONTS & TYPESETTING */
 
+.md-typeset {
+  font-weight: 400;
+}
+
+/* Makes links a little bolder */
+.md-typeset a {
+  font-weight: 600;
+
+}
+
 .md-typeset h1 {
   font-weight: 700;
   /* font-size: 24pt; */

docs/integrator/faqs-for-integrators.md

@@ -33,10 +33,6 @@ By using the RCPCH-provided API, you avoid all that requirement and use our comm
 
 From a DPCHR implementer perspective, if a birth notification has not flowed into the DPCHR, suppliers will need to require parents to enter it.
 
-* [DPCHR]: Digital Paediatric Child Health Record
-* [DCB0129]: (Data Coordination Board) Standard 0129
-* [DCB0160]: (Data Coordination Board) Standard 0160
-
 ## Q: What development effort is required to integrate this API into an app or Electronic Patient Record?
 
 **A**: Minimal development is required. The tricky stuff (calculating centiles from complex statistical tables, selecting the correct UK90 or WHO references for age, and gestational age correction) is all done for you. The data returned will be the correct centiles, which can be displayed to the user.
@@ -45,13 +41,13 @@ Producing a visual ‘growth chart’ with this data is a little more involved,
 
 We are keen to build a ‘catalogue’ of chart clients, so other open-source clients are very welcome. We will also help you build and test them!
 
-## Q: Is corrected gestational age passed back by the API, or do implementers have to calculate it?
+## Q: Is corrected gestational age passed back by the API?
 
 **A**: Yes, corrected age is passed back by the API, if a gestational age is included in the request.
 
 **NOTE: The API can only correct for gestational age if a gestational age has been supplied!**
 
-This correction is applied up to the corrected age of 1 year for preterm children born above 32 weeks, and to the corrected age of 2 years for preterm children born below 32 weeks, which is accepted standard practice among paediatricians.
+This correction is applied throughout the life course. (In the past the correction was only applied to 1 or 2 years depending on the degree of prematurity. This is no longer the case, following an RCPCH dGC Project Board decision. It is trivial to have the computer correct throughout the life course, so we made this the default. Uncorrected age is still available in the API response, if required.)
 
 ## Q: Does my application need to validate inputs?
 
@@ -65,6 +61,8 @@ This correction is applied up to the corrected age of 1 year for preterm childre
 
 **A**: Maybe. It would depend on the implementation.
 
-Images of charts are definitely **not** good enough for calculating a centile from, although many GP software packages do it this way. It is poor practice, and it's why the API needed to exist in the first place. However, since we are calculating the centiles for you, the chart is only for displaying the trend. An image **could** be used, but we generally advise against it.
+Images of charts are definitely **not** good enough for calculating a centile from, although many General Practice software packages currently do it this way. Plotting on an image is a hack, and it's why we had to create the API in the first place. However, since we are calculating the centiles for you, the chart is only for displaying the trend. An image **could** be used, but we generally advise against it.
 
 It is very easy to accidentally offset or incorrectly scale images, leading to *some* correctly plotted points, but others not. The best practice is to always use the *same* vector graphic tooling to both construct lines **and** plot the points, avoiding offsets/scaling inaccuracy. If you use an image (against our advice), you must ensure the correct one is selected for the presented data. More, you must ensure scaling and offset are not just programmed to be correct, but also clinically tested to be correct!
+
+We would in every situation recommend using the [React Chart Component](../products/react-component.md) to render the chart. It is open-source, and can be used as a reference implementation if you wish to build your own.

docs/internal/azure-apim.md

@@ -0,0 +1,48 @@
+---
+title: Azure API Management Platform
+reviewers: Dr Marcus Baw
+audience: rcpch-staff
+---
+
+!!! warning
+    **THIS PAGE IS INTENTIONALLY HIDDEN FROM THE NAVIGATION MENU.** <br/>
+    **IT IS NOT INTENDED FOR PUBLIC CONSUMPTION.**
+
+We use the Azure API Management platform to manage access to the API. It functions as a central 'proxy' server, intercepting all requests to our API and checking that the user has a valid subscription, before passing valid requests on to the individual API backend services, for example the Digital Growth Charts API server.
+
+This allows us to have a single point of access for all our APIs, and to manage access to them centrally. It also allows us to monitor usage of the APIs, and to set limits on the number of requests that can be made.
+
+## Azure APIM
+
+There are three important URLs for the Azure APIM, and it's important to understand the difference between them, and what they are each used for.
+
+### [portal.azure.com](https://portal.azure.com/#@rcpch.ac.uk/resource/subscriptions/99e313f5-79fe-4480-b867-8daf2800cf22/resourceGroups/RCPCH-Dev-API-Growth/providers/Microsoft.ApiManagement/service/RCPCH-Growth-Charts/overview)
+
+This is the RCPCH's Azure Portal Admin backend, where we can see and configure the APIM service. You will need to log in with your RCPCH Microsoft account. If you can't access it, you need to ask the RCPCH IT team to enable access.
+
+### [dev.rcpch.ac.uk](https://dev.rcpch.ac.uk)
+
+This is the 'Developer Portal', a website where customers can create and manage subscriptions to the API. They create an account using an email address and a password, and then can create an 'app', which can then be connected to an API subscription. They can then use the API keys generated from within this portal to access the API. API requests sent to `dev.rcpch.ac.uk` will be ignored.
+
+### [api.rcpch.ac.uk](https://api.rcpch.ac.uk)
+
+This is the API 'Gateway', a service URL which is where the API requests are sent by our customers. Importantly it is **not** the developer portal. API keys must be supplied in the authentication header of the request, and the APIM will check that the key is valid before passing the request on to the API backend service. Visiting this URL in a normal browser will result in a 404 Not Found error.
+
+## Finding and managing a User
+
+* It is much easier to search for Users than Subscriptions. Go to the [Users](https://portal.azure.com/#@rcpch.ac.uk/resource/subscriptions/99e313f5-79fe-4480-b867-8daf2800cf22/resourceGroups/RCPCH-Dev-API-Growth/providers/Microsoft.ApiManagement/service/RCPCH-Growth-Charts/apim-users) section by following the link, or by finding it in the left sidebar.
+* Using the filter box, the User list can be searched by Email or by Full Name.
+* The list can be sorted by clicking on the column headers.
+* Once you have found the User you are looking for, click on their name to open their profile.
+* For active users, a password reset can be initiated for them from this page - however it is advised that they are asked to do this themselves from the Developer Portal.
+* Click on the Subscriptions to see a list of all their subscriptions.
+
+## Managing a Subscription
+
+* Once the Subscription is identified, clicking on that row will open the Subscription details.
+* In this screen it is possible to:
+  * Amend the **Display name** of the Subscription. This is the name that will be displayed in the Developer Portal, and it is the only searchable field when the [Subscriptions view](https://portal.azure.com/#@rcpch.ac.uk/resource/subscriptions/99e313f5-79fe-4480-b867-8daf2800cf22/resourceGroups/RCPCH-Dev-API-Growth/providers/Microsoft.ApiManagement/service/RCPCH-Growth-Charts/apim-subscriptions) is being used in the APIM Portal.
+  * Change the **Scope** of the Subscription's API access. This can either be 'All APIs', a specific single API, or a Product. At RCPCH we have our APIs grouped into Products, so that a single subscription can be used to access multiple APIs. This is useful for customers who want to use both the Digital Growth Charts and other APIs.
+  * Change the **Product** that the Subscription is associated with. This is only relevant if the Scope is set to 'Product', and will be greyed out otherwise.
+* The most likely admin action is to upgrade or downgrade a Subscription between Products. For example if a customer has paid to upgrade from the Free Tier to the Enterprise Tier, this is one area that the upgrade can be done.
+* **To save changes, click the Save button at the bottom of the screen.**

includes/_abbreviations.md

@@ -13,6 +13,8 @@
 *[CSCR]: Clinical Safety Case Report
 *[CSO]: Clinical Safety Officer
 *[DCB]: Data Coordination Board
+*[DCB0129]: (Data Coordination Board) Standard 0129
+*[DCB0160]: (Data Coordination Board) Standard 0160
 *[dGC]: Digital Growth Charts
 *[DPCHR]: Digital Paediatric Child Health Record
 *[DPO]: Data Protection Officer

mkdocs.yml

@@ -84,6 +84,15 @@ nav:
     - 'technical/status.md'
   - Contact: 'about/contact.md'
 
+# `not_in_nav` will prevent 'The following pages exist in the docs directory, but are not included in the "nav" configuration:' warnings
+not_in_nav: |
+  _assets/_snippets/dgc-platform-comprises.md
+  _assets/_snippets/docs-contributions.md
+  _assets/_snippets/htn-award.md
+  _assets/_snippets/self-host-warning.md
+  _utilities/page-template.md
+  internal/azure-apim.md
+
 theme:
   name: material
   custom_dir: rcpch-theme
@@ -165,7 +174,7 @@ markdown_extensions:
   - pymdownx.snippets:
       check_paths: true
       auto_append:
-        - includes/_abbreviations.md
+        - includes/_abbreviations.md # adds abbreviations snippets to ALL pages
   - pymdownx.superfences
   - toc:
       permalink: false