Add command to Make docs

CHANGELOG.md

@@ -12,15 +12,18 @@ ENHANCEMENTS:
 * Add Windows Server 2025 image support to Guacamole. ([#4890](https://github.com/microsoft/AzureTRE/issues/4890))
 * Add support for setting resource processor VMSS SKU via environment variables ([#4936](https://github.com/microsoft/AzureTRE/issues/4936))
 * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920))
+* Add support for formatting UI code via `pre-commit` and fix existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955))
+* Update the version of `super-linter` used in the `build_validation_develop` workflow to 8.7.0 ([#4957](https://github.com/microsoft/AzureTRE/issues/4957))
+* Add `make docs` to build and preview documentation ([#5007](https://github.com/microsoft/AzureTRE/issues/5007))
 
 BUG FIXES:
 * Fix Nexus shared service security: fetch admin password from Key Vault at runtime via managed identity (IMDS) instead of embedding it in the VM Run Command script content. Fix `deploy_nexus_container.sh` short-circuit path to fail loudly if the container does not start. (`sonatype-nexus` 3.10.0) ([#4983](https://github.com/microsoft/AzureTRE/pull/4983))
 * Fix UI TypeScript deprecation warning by updating `moduleResolution` to `bundler` in `tsconfig.json`. ([#4968](https://github.com/microsoft/AzureTRE/issues/4968))
 * Fix API timeout and name collision failures on workspace creation by checking storage account name availability and improved logging. ([#4946](https://github.com/microsoft/AzureTRE/pull/4946))
 * Fix error handling in airlock processor ([#4929](https://github.com/microsoft/AzureTRE/pull/4929))
 * Update allowed URLs in Nexus for letsencrypt ([#4899](https://github.com/microsoft/AzureTRE/pull/4899))
-* Fix dependabot high severity alerts for packages fast-uri, lodash, picomatch, immutable, minimatch, flatted and PyJWT
-* Fix dependabot high moderate alerts for packages aiohttp and pytest, pytest-asyncio
+* Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. ([#4914](https://github.com/microsoft/AzureTRE/issues/4914))
+* Update dependencies to address Dependabot security alerts: `aiohttp`, `pytest`, `pytest-asyncio`, `Pygments`, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4915](https://github.com/microsoft/AzureTRE/issues/4915), [#4950](https://github.com/microsoft/AzureTRE/issues/4950))
 * Fix spelling in docs using codespell ([#4954](https://github.com/microsoft/AzureTRE/issues/4954))
 * Fix issues identified by flake8 ([#4958](https://github.com/microsoft/AzureTRE/issues/4958))
 * Replace deprecated yaspell with codespell and add pre-commit hook installer to devcontainer. ([#4953](https://github.com/microsoft/AzureTRE/issues/4953))
@@ -41,7 +44,7 @@ ENHANCEMENTS:
 BUG FIXES:
 * Fix OpenAPI/schema sample generation for `get_sample_operation` step parameters. ([#4864](https://github.com/microsoft/AzureTRE/issues/4864))
 * Fix test airlock request sample data fields and enum values. ([#4866](https://github.com/microsoft/AzureTRE/issues/4866))
-* Fix property substitution not occuring where there is only a main step in the pipeline ([#4824](https://github.com/microsoft/AzureTRE/issues/4824))
+* Fix property substitution not occurring where there is only a main step in the pipeline ([#4824](https://github.com/microsoft/AzureTRE/issues/4824))
 * Fix Mysql template ignored storage_mb ([#4846](https://github.com/microsoft/AzureTRE/issues/4846))
 * Fix duplicate `TOPIC_SUBSCRIPTION_NAME` in `core/terraform/airlock/airlock_processor.tf` ([#4847](https://github.com/microsoft/AzureTRE/pull/4847))
 * Fix Nexus repository access blocked by unaccepted EULA in Nexus 3.77+ Community Edition ([#4842](https://github.com/microsoft/AzureTRE/issues/4842))
@@ -103,7 +106,7 @@ BUG FIXES:
 * Fix Azure Health Data Services deployment failures by upgrading AzureRM provider to 4.58.0, switching to RBAC group assignments, and adding workspace group parameter mappings ([#4844](https://github.com/microsoft/AzureTRE/issues/4844))
 * Replace deprecated `--username` flag with `--client-id` in `az login --identity` commands across all Porter bundles ([#4817](https://github.com/microsoft/AzureTRE/issues/4817))
 * Fix deleted workspaces still accessible via URL - get_*_by_id methods now filter out deleted resources ([#4785](https://github.com/microsoft/AzureTRE/issues/4785))
-* Fix circular dependancy in base workspace. ([#4756](https://github.com/microsoft/AzureTRE/pull/4756))
+* Fix circular dependency in base workspace. ([#4756](https://github.com/microsoft/AzureTRE/pull/4756))
 * Replaced deprecated `datetime.utcnow()` with `datetime.now(datetime.UTC)` in the API and airlock processor. ([#4743](https://github.com/microsoft/AzureTRE/issues/4743))
 * Updated error messages when publishing a template version that is lower than the existing version. ([#4685](https://github.com/microsoft/AzureTRE/issues/4685))
 * Disable public access on stweb storage account ([#4766](https://github.com/microsoft/AzureTRE/issues/4766))
@@ -701,7 +704,7 @@ BUG FIXES:
 * Airlock: Creating an import/export request causes a routing error ([#3830](https://github.com/microsoft/AzureTRE/issues/3830))
 * Fix registration of templates with no 'authorizedRoles' or 'required' defined ([#3849](https://github.com/microsoft/AzureTRE/pull/3849))
 * Update terraform for services bus to move network rules into namespace resource to avoid depreciation warning, and update setup_local_debugging.sh to use network_rule_sets ([#3858](https://github.com/microsoft/AzureTRE/pull/3858))
-* Update terraform MySQL resources to MySQL Flexible resources to fix depricating recources. ([#3892](https://github.com/microsoft/AzureTRE/pull/3892))
+* Update terraform MySQL resources to MySQL Flexible resources to fix deprecating resources. ([#3892](https://github.com/microsoft/AzureTRE/pull/3892))
 * Fix issue with firewall failing to deploy on a new TRE deploy ([#3775](https://github.com/microsoft/AzureTRE/issues/3775))
 
 COMPONENTS:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap-init mgmt-deploy mgmt-destroy build-api-image push-api-image tre-deploy tre-destroy letsencrypt
+.PHONY: bootstrap-init mgmt-deploy mgmt-destroy build-api-image push-api-image tre-deploy tre-destroy letsencrypt docs
 .DEFAULT_GOAL := help
 
 SHELL:=/bin/bash
@@ -265,6 +265,14 @@ lint: ## 🧹 Lint all files
 lint-docs:
 	LINTER_REGEX_INCLUDE='./docs/.*\|./mkdocs.yml' $(MAKE) lint
 
+# Description: Documentation helper target
+# Single target `make docs` will install deps and serve the site locally (default). Set MODE=build for build-only mode.
+# Example: make docs            -> installs deps and serves site locally
+# Example: make docs MODE=build -> installs deps and builds site only
+docs: ## Install docs deps and build/serve the MkDocs site
+	@bash ./devops/scripts/docs.sh $(MODE)
+
+
 # Description: Build the bundle with Porter.
 # # check-params is called at the end since it needs the bundle image,
 # # so we build it first and then run the check.

devops/scripts/docs.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PY=python3
+VENV=.venv
+REQS=docs/requirements.txt
+
+PORT=${PORT:-8000}
+
+usage(){
+  echo "Usage: $0 [build|serve|install]" >&2
+  exit 2
+}
+
+if [ "$#" -gt 1 ]; then
+  usage
+fi
+
+CMD=${1:-serve}
+
+if [ ! -f "$REQS" ]; then
+  echo "Requirements file not found: $REQS" >&2
+  exit 1
+fi
+
+if [ ! -d "$VENV" ]; then
+  echo "Creating virtualenv at $VENV"
+  $PY -m venv "$VENV"
+fi
+
+# shellcheck disable=SC1091
+source "$VENV/bin/activate"
+
+pip install --upgrade pip
+pip install -r "$REQS"
+
+get_free_port() {
+  local start_port="${1:-8000}"
+  "$PY" -c "
+import socket
+start = $start_port
+for p in range(start, start + 100):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(('127.0.0.1', p))
+            print(p)
+            break
+        except OSError:
+            continue
+"
+}
+
+case "$CMD" in
+  build)
+    echo "Building mkdocs site..."
+    "$VENV/bin/mkdocs" build --strict
+    ;;
+  serve)
+    FREE_PORT=$(get_free_port "$PORT")
+    if [ "$FREE_PORT" != "$PORT" ]; then
+      echo "Port $PORT is in use. Using next available port: $FREE_PORT"
+    fi
+    echo "Starting mkdocs serve (http://127.0.0.1:${FREE_PORT})..."
+    "$VENV/bin/mkdocs" serve -a "127.0.0.1:${FREE_PORT}"
+    ;;
+  install)
+    echo "Installed documentation dependencies into $VENV"
+    ;;
+  *)
+    usage
+    ;;
+esac

docs/contributing.md

@@ -28,4 +28,29 @@
 
   * [Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose)
 
+## Building and Serving Documentation Locally
+
+To preview and test changes to the documentation site locally:
+
+* **Serve documentation locally (default)**:
+  ```bash
+  make docs
+  ```
+  This installs required dependencies, selects the first available port (starting at `8000`), and starts the local MkDocs server.
+
+  You can also specify a custom port:
+  ```bash
+  PORT=8100 make docs
+  ```
+
+* **Build documentation (build-only)**:
+  ```bash
+  make docs MODE=build
+  ```
+
+* **Lint documentation files**:
+  ```bash
+  make lint-docs
+  ```
+
 Thanks! :heart: :heart: :heart: