chore: add api docs in mkdocs build (aws-powertools#3715)

Author: dreamorosi

.github/workflows/reusable_publish_docs.yml

@@ -82,10 +82,6 @@ jobs:
         run: |
           rm -rf site
           mkdocs build
-      - name: Build API docs
-        run: |
-          rm -rf api
-          npm run docs-generateApiDoc
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@ececac1a45f3b08a01d2dd070d28d111c5fe6722 # v4.1.0
         with:

CONTRIBUTING.md

@@ -115,9 +115,35 @@ GitHub provides additional document on [forking a repository](https://help.githu
 
 You might find useful to run both the documentation website and the API reference locally while contributing:
 
-- **Docs website**: `npm run docs-runLocalDocker`
-    - If this is your first time running the docs, you need to build the image: `npm run docs-buildDockerImage`
-- **API reference**: `npm run docs-api-build-run`
+#### Using Docker (recommended)
+
+1. Build the Docker image (only needed the first time):
+
+   ```bash
+   npm run docs:docker:build
+   ```
+
+2. Run the documentation website:
+
+   ```bash
+   npm run docs:docker:run
+   ```
+
+#### Using Python directly
+
+If you have Python 3.x installed, you can run the documentation website and API reference locally without Docker:
+
+1. Create a virtual environment and install dependencies:
+
+   ```bash
+   npm run docs:local:setup
+   ```
+
+2. Run the documentation website:
+
+   ```bash
+   npm run docs:local:run
+   ```
 
 ## Conventions
 

README.md

@@ -1,5 +1,5 @@
 <!-- markdownlint-disable MD013  -->
-# Powertools for AWS Lambda (TypeScript) <!-- omit in toc -->
+# Powertools for AWS Lambda (TypeScript)
 
 ![NodeSupport](https://img.shields.io/static/v1?label=node&message=%2018|%2020|%2022&color=green?style=flat-square&logo=node)
 ![GitHub Release](https://img.shields.io/github/v/release/aws-powertools/powertools-lambda-typescript?style=flat-square)

docs/Dockerfile

@@ -1,5 +1,8 @@
 # version 9.5.35
 FROM squidfunk/mkdocs-material@sha256:047452c6641137c9caa3647d050ddb7fa67b59ed48cc67ec3a4995f3d360ab32
 
+# Install Node.js
+RUN apk add --no-cache nodejs=20.15.1-r0 npm
+
 COPY requirements.txt /tmp/
 RUN pip install --require-hashes -r /tmp/requirements.txt

docs/contributing/setup.md

@@ -65,10 +65,36 @@ You can use `npm run setup-local` to install all dependencies locally and setup
 !!! note "Curious about what `setup-local` does under the hood?"
     We use npm scripts to [automate common tasks](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/package.json#L24){target="_blank" rel="nofollow"} locally and in Continuous Integration environments.
 
-## Local documentation
+### Local documentation
 
 You might find useful to run both the documentation website and the API reference locally while contributing:
 
-* **Docs website**: `npm run docs-runLocalDocker`
-    * If this is your first time running the docs, you need to build the image: `npm run docs-buildDockerImage`
-* **API reference**: `npm run docs-api-build-run`
+#### Using Docker (recommended)
+
+1. Build the Docker image (only needed the first time):
+
+   ```bash
+   npm run docs:docker:build
+   ```
+
+2. Run the documentation website:
+
+   ```bash
+   npm run docs:docker:run
+   ```
+
+#### Using Python directly
+
+If you have Python installed, you can run the documentation website and API reference locally without Docker:
+
+1. Create a virtual environment and install dependencies:
+
+   ```bash
+   npm run docs:local:setup
+   ```
+
+2. Run the documentation website:
+
+   ```bash
+   npm run docs:local:run
+   ```

docs/requirements.in

@@ -1,4 +1,5 @@
 mike==1.1.2
 mkdocs-material==9.6.7
 mkdocs-git-revision-date-plugin==0.3.2
-mkdocs-exclude==1.0.2
+mkdocs-exclude==1.0.2
+mkdocs-typedoc==1.0.4

docs/requirements.txt

@@ -1,8 +1,8 @@
 #
-# This file is autogenerated by pip-compile with Python 3.12
+# This file is autogenerated by pip-compile with Python 3.13
 # by the following command:
 #
-#    pip-compile --generate-hashes --output-file=requirements.txt requirements.in
+#    pip-compile --generate-hashes --output-file=docs/requirements.txt docs/requirements.in
 #
 babel==2.16.0 \
     --hash=sha256:368b5b98b37c06b7daf6696391c3240c938b37767d4584413e8438c5c435fa8b \
@@ -224,7 +224,7 @@ mergedeep==1.3.4 \
 mike==1.1.2 \
     --hash=sha256:4c307c28769834d78df10f834f57f810f04ca27d248f80a75f49c6fa2d1527ca \
     --hash=sha256:56c3f1794c2d0b5fdccfa9b9487beb013ca813de2e3ad0744724e9d34d40b77b
-    # via -r requirements.in
+    # via -r docs/requirements.in
 mkdocs==1.6.1 \
     --hash=sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2 \
     --hash=sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e
@@ -233,24 +233,29 @@ mkdocs==1.6.1 \
     #   mkdocs-exclude
     #   mkdocs-git-revision-date-plugin
     #   mkdocs-material
+    #   mkdocs-typedoc
 mkdocs-exclude==1.0.2 \
     --hash=sha256:ba6fab3c80ddbe3fd31d3e579861fd3124513708271180a5f81846da8c7e2a51
-    # via -r requirements.in
+    # via -r docs/requirements.in
 mkdocs-get-deps==0.2.0 \
     --hash=sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c \
     --hash=sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134
     # via mkdocs
 mkdocs-git-revision-date-plugin==0.3.2 \
     --hash=sha256:2e67956cb01823dd2418e2833f3623dee8604cdf223bddd005fe36226a56f6ef
-    # via -r requirements.in
+    # via -r docs/requirements.in
 mkdocs-material==9.6.7 \
     --hash=sha256:3e2c1fceb9410056c2d91f334a00cdea3215c28750e00c691c1e46b2a33309b4 \
     --hash=sha256:8a159e45e80fcaadd9fbeef62cbf928569b93df954d4dc5ba76d46820caf7b47
-    # via -r requirements.in
+    # via -r docs/requirements.in
 mkdocs-material-extensions==1.3.1 \
     --hash=sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443 \
     --hash=sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31
     # via mkdocs-material
+mkdocs-typedoc==1.0.4 \
+    --hash=sha256:839b54c51a64bbb77c1c253eb81baad12462ea5cf38d361e262f5cfa8a45567a \
+    --hash=sha256:a9601d6b04ed4fd5658c7170c58a3a52f584357be2a3c1e39995c6eed3712b1e
+    # via -r docs/requirements.in
 packaging==24.1 \
     --hash=sha256:026ed72c8ed3fcce5bf8950572258698927fd1dbda10a5e981cdf0ac37f4f002 \
     --hash=sha256:5b8f2217dbdbd2f7f384c41c628544e6d52f2d0f53c6d0c3ea61aa5d1d7ff124

examples/snippets/validation/.gitignore

@@ -4,12 +4,35 @@ site_author: Amazon Web Services
 repo_url: https://github.com/aws-powertools/powertools-lambda-typescript
 edit_uri: edit/main/docs
 site_url: https://docs.powertools.aws.dev/lambda/typescript
+watch: [
+  docs,
+  packages/batch/src,
+  examples/snippets/batch,
+  packages/commons/src,
+  packages/event-handler/src,
+  examples/snippets/event-handler,
+  packages/idempotency/src,
+  examples/snippets/idempotency,
+  packages/jmespath/src,
+  examples/snippets/jmespath,
+  packages/logger/src,
+  examples/snippets/logger,
+  packages/metrics/src,
+  examples/snippets/metrics,
+  packages/parameters/src,
+  examples/snippets/parameters,
+  packages/parser/src,
+  examples/snippets/parser,
+  packages/tracer/src,
+  examples/snippets/tracer,
+  packages/validation/src,
+  examples/snippets/validation,
+]
 
 nav:
   - Homepage:
       - index.md
       - Changelog: changelog.md
-      - API reference: api/" target="_blank
       - Upgrade guide: upgrade.md
       - We Made This (Community): we_made_this.md
       - Workshop: https://s12d.com/powertools-for-aws-lambda-workshop" target="_blank
@@ -23,6 +46,7 @@ nav:
           - utilities/batch.md
           - utilities/jmespath.md
           - utilities/parser.md
+  - API reference: api"
   - Processes:
       - Roadmap: roadmap.md
       - Versioning policy: versioning.md
@@ -101,7 +125,7 @@ markdown_extensions:
   - pymdownx.tasklist:
       custom_checkbox: true
 
-copyright: Copyright © 2023 Amazon Web Services
+copyright: Copyright © 2025 Amazon Web Services
 
 plugins:
   - privacy
@@ -112,6 +136,12 @@ plugins:
         - snippets/node_modules/*
         - snippets/package.json
         - snippets/CHANGELOG.md
+  - typedoc:
+      source: '.'
+      output_dir: 'api'
+      tsconfig: 'tsconfig.json'
+      options: 'typedoc.json'
+      name: 'API Reference'
 
 extra_css:
   - stylesheets/extra.css

mkdocs.yml

@@ -27,12 +27,11 @@
     "commit": "commit",
     "setup-local": "npm ci && npm run build && husky",
     "build": "npm run build -ws",
-    "docs-website-build-run": "npm run docs-buildDockerImage && npm run docs-runLocalDocker",
-    "docs-buildDockerImage": "docker build -t powertools-typescript/docs ./docs/",
-    "docs-runLocalDocker": "docker run --rm -it -p 8000:8000 -v ${PWD}:/docs powertools-typescript/docs",
-    "docs-api-build-run": "npm run docs-generateApiDoc && npx live-server api",
-    "docs-generateApiDoc": "typedoc .",
-    "docs-runLocalApiDoc": "npx live-server api",
+    "docs:docker:build": "docker build -t powertools-typescript/docs ./docs/",
+    "docs:docker:run": "docker run --rm -it -p 8000:8000 -v ${PWD}:/docs powertools-typescript/docs",
+    "docs:local:setup": "python3 -m venv .venv && .venv/bin/pip install -r docs/requirements.txt",
+    "docs:local:run": ".venv/bin/mkdocs serve",
+    "docs:local:api": "typedoc .",
     "postpublish": "git restore .",
     "lint:markdown": "markdownlint-cli2 '**/*.md' '#node_modules' '#**/*/node_modules' '#docs/changelog.md' '#LICENSE.md' '#.github' '#**/*/CHANGELOG.md' '#examples/app/README.md'"
   },