chore(docs): migrate docs build from MkDocs to Zensical

.github/workflows/quality_check_docs.yml

@@ -47,4 +47,4 @@ jobs:
       - name: Build docs
         run: |
           rm -rf site
-          mkdocs build
+          zensical build

.github/workflows/reusable_publish_docs.yml

@@ -79,7 +79,7 @@ jobs:
           ALIAS: ${{ inputs.alias }}
         run: |
           rm -rf site
-          mkdocs build
+          zensical build
       - name: Deploy Docs (Version)
         env:
           VERSION: ${{ inputs.version }}

Makefile

@@ -56,11 +56,11 @@ build: pr
 	uv build --no-sources
 
 docs-local:
-	uv run --locked mkdocs serve
+	uv run --locked zensical serve
 
 docs-local-docker:
-	docker build -t squidfunk/mkdocs-material ./docs/
-	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+	docker build -t powertools-docs ./docs/
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs powertools-docs
 
 security-baseline:
 	uv run --locked bandit --baseline bandit.baseline -r aws_lambda_powertools

aws_lambda_powertools/metrics/base.py

@@ -1,7 +1,7 @@
 """
 Metrics utility
 !!! abstract "Usage Documentation"
-    [`Metrics`](../../core/metrics.md)
+    [`Metrics`](../../core/metrics/index.md)
 """
 
 from __future__ import annotations

docs/Dockerfile

@@ -1,5 +1,13 @@
-# v9.1.18
-FROM squidfunk/mkdocs-material@sha256:868ad4d39fb5865b72d00173ade00f4eae2b38dde7ff790a011cc44ce4a8ff8e
+# Local docs preview with Zensical (see `make docs-local-docker`)
+# python:3.12-slim
+FROM python@sha256:a6e34c598f2467ed0e9a8d349809fcd8b5c603269512df273a0bb1784edc11b1
 # pip-compile --generate-hashes --output-file=requirements.txt requirements.in
 COPY requirements.txt /tmp/
-RUN pip install --require-hashes -r /tmp/requirements.txt
+RUN pip install --no-cache-dir --require-hashes -r /tmp/requirements.txt
+# Same UID as the typical host user, so files written to the mounted volume are not owned by root
+RUN useradd --uid 1000 --create-home docs
+USER docs
+WORKDIR /docs
+EXPOSE 8000
+ENTRYPOINT ["zensical"]
+CMD ["serve", "--dev-addr", "0.0.0.0:8000"]

docs/core/event_handler/api_gateway.md

@@ -23,7 +23,7 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Load Balanc
 
 ### Install
 
-!!! info "This is not necessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../../index.md#lambda-layer){target="_blank"}."
+!!! info "This is not necessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../../getting-started/install.md#lambda-layer){target="_blank"}."
 
 **When using the data validation feature**, you need to add `pydantic` as a dependency in your preferred tool _e.g., requirements.txt, pyproject.toml_. At this time, we only support Pydantic V2.
 
@@ -64,7 +64,7 @@ By default, we will use `APIGatewayRestResolver` throughout the documentation. Y
 | **[`ALBResolver`](#application-load-balancer)**         | Amazon Application Load Balancer (ALB) |
 | **[`LambdaFunctionUrlResolver`](#lambda-function-url)** | AWS Lambda Function URL                |
 | **[`VPCLatticeResolver`](#vpc-lattice)**                | Amazon VPC Lattice                     |
-| **[`HttpResolverLocal`](#http-resolver-local)**         | ASGI-compatible resolver               |
+| **[`HttpResolverLocal`](#http-resolver-asgi)**         | ASGI-compatible resolver               |
 <!-- markdownlint-enable MD051 -->
 
 #### Response auto-serialization

docs/core/event_handler/bedrock_agents.md

@@ -57,7 +57,7 @@ An action group defines actions that the agent can help the user perform. You ca
 
 ### Install
 
-!!! info "This is unnecessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../../index.md#lambda-layer){target="_blank"}."
+!!! info "This is unnecessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../../getting-started/install.md#lambda-layer){target="_blank"}."
 
 If you define the action group setting up an **OpenAPI schema**, you need to add `pydantic` as a dependency in your preferred tool _e.g., requirements.txt, pyproject.toml_. At this time, we only support Pydantic V2.