docs: separate API reference documentation from README customer section

.gitignore

@@ -53,4 +53,7 @@ tsconfig.tsbuildinfo
 .amazonq
 .kiro
 .github/instructions
-aidlc-docs
+aidlc-docs
+# Generated by docs/generate_api_readme.py - do not commit
+API_README.md
+packages/*/API_README.md

docs/generate_api_readme.py

@@ -0,0 +1,44 @@
+"""
+Generate API_README.md files for TypeDoc by stripping the customer reference section
+from each package's README.md and the root README.md.
+
+Registered as an mkdocs on_pre_build hook so it runs automatically during `mkdocs build`.
+Can also be run standalone: python3 docs/generate_api_readme.py
+"""
+
+import re
+from pathlib import Path
+
+
+# Removes the full section body (heading through the last sub-section before ## License)
+SECTION_PATTERN = re.compile(
+    r"\n## How to support Powertools for AWS Lambda \(TypeScript\)\?.*?(?=\n## )",
+    re.DOTALL,
+)
+
+# Removes the TOC entry and its indented children
+TOC_ENTRY_PATTERN = re.compile(
+    r"\n- \[How to support Powertools for AWS Lambda \(TypeScript\)\?[^\n]*"
+    r"(?:\n    - \[[^\n]*)*",
+)
+
+
+def generate(root: Path = Path(".")) -> None:
+    targets = [root] + sorted((root / "packages").iterdir())
+    for pkg in targets:
+        readme = pkg / "README.md"
+        if not readme.exists():
+            continue
+        content = readme.read_text(encoding="utf-8")
+        clean = SECTION_PATTERN.sub("", content)
+        clean = TOC_ENTRY_PATTERN.sub("", clean)
+        (pkg / "API_README.md").write_text(clean, encoding="utf-8")
+
+
+# mkdocs hook entry point
+def on_pre_build(config) -> None:  # noqa: ANN001
+    generate()
+
+
+if __name__ == "__main__":
+    generate()

mkdocs.yml

@@ -1,3 +1,6 @@
+hooks:
+  - docs/generate_api_readme.py
+
 site_name: Powertools for AWS Lambda (TypeScript)
 site_description: Powertools for AWS Lambda (TypeScript)
 site_author: Amazon Web Services

package.json

@@ -31,7 +31,7 @@
     "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 .",
+    "docs:local:api": "python3 docs/generate_api_readme.py && typedoc .",
     "postpublish": "git restore .",
     "lint:markdown": "markdownlint-cli2 '**/*.md' '#node_modules' '#**/*/node_modules' '#docs/changelog.md' '#LICENSE.md' '#.github' '#CHANGELOG.md' '#**/*/CHANGELOG.md' '#examples/app/README.md' '#.venv' '#site'"
   },

packages/batch/typedoc.json

@@ -1,5 +1,5 @@
 {
   "extends": ["../../typedoc.base.json"],
   "entryPoints": ["./src/index.ts", "./src/parser.ts", "./src/types.ts"],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/commons/typedoc.json

@@ -9,5 +9,5 @@
     "./src/fromBase64.ts",
     "./src/LRUCache.ts"
   ],
-  "readme": "./README.md"
+  "readme": "./API_README.md"
 }

packages/event-handler/typedoc.json

@@ -7,5 +7,5 @@
     "./src/http/index.ts",
     "./src/types/index.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/idempotency/typedoc.json

@@ -9,5 +9,5 @@
     "./src/persistence/CachePersistenceLayer.ts",
     "./src/types/CachePersistence.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/jmespath/typedoc.json

@@ -7,5 +7,5 @@
     "./src/Functions.ts",
     "./src/PowertoolsFunctions.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/kafka/typedoc.json

@@ -1,5 +1,5 @@
 {
   "extends": ["../../typedoc.base.json"],
   "entryPoints": ["./src/index.ts", "./src/types/types.ts", "./src/errors.ts"],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/logger/typedoc.json

@@ -5,5 +5,5 @@
     "./src/types/index.ts",
     "./src/middleware/middy.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/metrics/typedoc.json

@@ -5,5 +5,5 @@
     "./src/types/index.ts",
     "./src/middleware/middy.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/parameters/typedoc.json

@@ -13,7 +13,7 @@
     "./src/errors.ts",
     "./src/constants.ts"
   ],
-  "readme": "README.md",
+  "readme": "./API_README.md",
   "externalSymbolLinkMappings": {
     "@aws-sdk/client-secrets-manager": {
       "GetSecretValueCommandInput": "https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-secrets-manager/Interface/GetSecretValueCommandInput/"

packages/parser/typedoc.json

@@ -9,5 +9,5 @@
     "./src/helpers/index.ts",
     "./src/helpers/dynamodb.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/tracer/typedoc.json

@@ -6,5 +6,5 @@
     "./src/middleware/middy.ts",
     "./src/provider/ProviderService.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

packages/validation/typedoc.json

@@ -7,5 +7,5 @@
     "./src/decorator.ts",
     "./src/errors.ts"
   ],
-  "readme": "README.md"
+  "readme": "./API_README.md"
 }

typedoc.json

@@ -2,7 +2,7 @@
   "entryPoints": ["packages/*"],
   "entryPointStrategy": "packages",
   "name": "Powertools for AWS Lambda (Typescript) API Reference",
-  "readme": "README.md",
+  "readme": "./API_README.md",
   "out": "api",
   "exclude": [
     "**/node_modules/**",