From 9efcaa2dbff067ec18287ac9a5d5d912dedc45b7 Mon Sep 17 00:00:00 2001
From: Michael Collins <15347726+michaeljcollinsuk@users.noreply.github.com>
Date: Thu, 23 Jan 2025 14:15:34 +0000
Subject: [PATCH] Jupyter formatting fix (#484)

* More formatting fixes to the Jupyter docs

* Add script to run docs locally

* Add alternative local running instructions

* Newline to preempt linting anger
---
 README.md                                     |  6 +++++
 scripts/local.sh                              | 27 +++++++++++++++++++
 .../appendix-docs/app_development.md          |  1 +
 .../documentation/tools/jupyterlab/index.md   | 17 ++++++++----
 4 files changed, 46 insertions(+), 5 deletions(-)
 create mode 100644 scripts/local.sh

diff --git a/README.md b/README.md
index 8bfdec89..a0b05ef8 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,12 @@ To preview the guidance locally on an MoJ Digital and Technology MacBook, you wi
 make preview
 ```
 
+If this method does not work, try running the below as an alternative:
+
+```
+bash scripts/local.sh
+```
+
 You can view the guidance on `http://localhost:4567` in your browser. Any content changes you make to your website will be updated in real time.
 
 To shut down the Middleman instance running on your machine, select ⌘+C.
diff --git a/scripts/local.sh b/scripts/local.sh
new file mode 100644
index 00000000..6ea2e66b
--- /dev/null
+++ b/scripts/local.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+MODE="${1:-preview}"
+TECH_DOCS_PUBLISHER_IMAGE="docker.io/ministryofjustice/tech-docs-github-pages-publisher@sha256:cd3513beca3fcaf5dd34cbe81a33b3ff30337d8ada5869b40a6454c21d6f7684" # v4.0.0
+
+case ${MODE} in
+package | preview)
+  true
+  ;;
+*)
+  echo "Usage: ${0} [package|preview]"
+  exit 1
+  ;;
+esac
+
+if [[ "$(uname -m)" == "aarch64" ]] || [[ "$(uname -m)" == "arm64" ]] && [[ "$(uname)" != "Darwin" ]]; then
+  PLATFORM_FLAG="--platform=linux/amd64"
+else
+  PLATFORM_FLAG=""
+fi
+
+docker run -it --rm ${PLATFORM_FLAG} \
+  --name "tech-docs-${MODE}" \
+  --publish 4567:4567 \
+  --volume "${PWD}/config:/app/config" \
+  --volume "${PWD}/source:/app/source" \
+  "${TECH_DOCS_PUBLISHER_IMAGE}" "/usr/local/bin/${MODE}"
diff --git a/source/documentation/appendix-docs/app_development.md b/source/documentation/appendix-docs/app_development.md
index 51bfe42e..f7b5a835 100644
--- a/source/documentation/appendix-docs/app_development.md
+++ b/source/documentation/appendix-docs/app_development.md
@@ -1,5 +1,6 @@
 > **IMPORTANT:**
 > These instructions are for older versions of JupyterLab earlier than v3.6.3-4.1.0.
+>
 > [You can find the latest documentation on running an application locally here](https://user-guidance.analytical-platform.service.justice.gov.uk/tools/jupyterlab/index.html#accessing-a-locally-running-application).
 
 
diff --git a/source/documentation/tools/jupyterlab/index.md b/source/documentation/tools/jupyterlab/index.md
index ecb9d93b..9ad4bad9 100644
--- a/source/documentation/tools/jupyterlab/index.md
+++ b/source/documentation/tools/jupyterlab/index.md
@@ -93,22 +93,29 @@ And then select the kernel in Jupyter as [normal](../tools/package-management.ht
 
 ## Accessing a Locally Running Application
 
-As of version JupyterLab v3.6.3-4.1.0, to access an application running locally (such as Dash or Streamlit), it *must* be running on port `8081`. You can then access it by visiting `https://${USERNAME}-jupyter-lab-tunnel.tools.analytical-platform.service.justice.gov.uk`. As apps are only accessible on port 8081, you can only run one app at a time.
+As of version `JupyterLab v3.6.3-4.1.0`, to access an application running locally (such as Dash or Streamlit), it **must** be running on port `8081`.
+
+You can then access it by visiting `https://${USERNAME}-jupyter-lab-tunnel.tools.analytical-platform.service.justice.gov.uk`. As apps are only accessible on port 8081, you can only run one app at a time.
 
 This cannot be accessed by anyone other than yourself as it uses the same authentication method as your tooling.
 
-There is no longer a requirement to run your app (e.g. Dash or Steamlit) on a base url path e.g. `/_tunnel_/8050/`. This is only required for older versions of JupyterLab that are now deprecated.
+There is no longer a requirement to run your app (e.g. Dash or Steamlit) on a base url path e.g. `/\_tunnel\_/8050/`. This is only required for older versions of JupyterLab that are now deprecated.
 
 ### Hints and tips
+
 - To run a Dash app on port `8081` use the `port` arg when using the `app.run` command in your code e.g.:
+
     ```
     if __name__ == '__main__':
         app.run(port=8081)
     ```
+
 - To run a Streamlit app on port `8081` you can use the `--server.port` flag when running the app e.g.
-   ```
-   streamlit run app.py --server.port 8081
-   ```
+
+    ```
+    streamlit run app.py --server.port 8081
+    ```
+
     Alternatively, set the server port environment variable in your terminal session before running your app `export STREAMLIT_SERVER_PORT=8081`