diff --git a/.github/workflows/reusable_publish_docs.yml b/.github/workflows/reusable_publish_docs.yml index 15d53aae7c..68cacc068a 100644 --- a/.github/workflows/reusable_publish_docs.yml +++ b/.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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c548ea5beb..1fb13dda87 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index f5d4d566b5..3057c33ca9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -# Powertools for AWS Lambda (TypeScript) +# 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) diff --git a/docs/Dockerfile b/docs/Dockerfile index 309fa6a2c6..5db3fb151f 100644 --- a/docs/Dockerfile +++ b/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 diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 68bcf2cba6..7f10903d87 100644 --- a/docs/contributing/setup.md +++ b/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 + ``` diff --git a/docs/requirements.in b/docs/requirements.in index d124923b00..99df90a461 100644 --- a/docs/requirements.in +++ b/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 \ No newline at end of file +mkdocs-exclude==1.0.2 +mkdocs-typedoc==1.0.4 \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 650a901075..4dff4bac49 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/examples/snippets/validation/.gitignore b/examples/snippets/validation/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/mkdocs.yml b/mkdocs.yml index 090841d535..994dc80125 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 diff --git a/package.json b/package.json index d8a4677cb0..255ae14623 100644 --- a/package.json +++ b/package.json @@ -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'" },