docs: separate API reference documentation from README customer section

[Zelys-DFKH]

Summary

The API reference includes a "Becoming a reference customer" section with company logos that shouldn't appear in the generated TypeDoc output. The original README.md (published to npm) keeps that section intact, so the fix has to happen at build time rather than by editing the source files.

docs/generate_api_readme.py strips the customer section and its TOC entry from each package's README.md and the root README.md, writing API_README.md files that TypeDoc references. The generated files are gitignored and never committed.

The script runs as an mkdocs on_pre_build hook so mkdocs build handles generation automatically with no CI workflow changes. The docs:local:api npm script runs it before calling typedoc directly.

Fixes #4594

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[dreamorosi]

Thanks for the PR - while this does resolve the issue, I am not sure I am in favor of duplicating the contents of each README in two files.

Doing this will introduce overhead to keep them updated which will most likely result in drift.

I don't have a good solution yet - which is also why the original issue was left unresolved - but this is where I stand now.

[Zelys-DFKH]

Thanks for the feedback—you're right about the maintenance burden. I want to propose something simpler.

Instead of keeping two files in sync, we could generate the API_README.md at build time. The script strips out the customer section from README.md and writes the cleaned version to a dist directory. TypeDoc references the generated file, not a committed one. This way there's only one source file to edit, filtering is automated, and zero risk of drift.

Here's the approach: add a script like scripts/generate-api-readme.sh that runs before the TypeDoc build. It removes the "How to support Powertools" section from each README and outputs API_README.md. Update each typedoc.json to point to the generated file instead of the source. The generated files don't get committed to git.

The result is clean API docs while npm packages keep the original README with customer logos intact. Does this direction work for the project? I can implement it if you want to go this route.

[dreamorosi]

Hi @Zelys-DFKH - thanks for engaging with the review feedback.

I think that could be a reasonable approach as long as it's not too brittle and it doesn't introduce too much build complexity.

Could you update the PR to show this mechanism you proposed so we can talk about it and test it?

[Zelys-DFKH]

Took the build-time generation approach. docs/generate_api_readme.py strips the customer section from each package's README.md and the root README.md, writing API_README.md files for TypeDoc. Nothing is committed.

The script runs as an mkdocs on_pre_build hook, so mkdocs build picks it up automatically with no CI changes. The docs:local:api npm script now runs it before calling typedoc directly.

One thing I caught while building: the TOC in each README has an entry pointing to the customer section. The script strips that too, so there are no broken anchor links in the rendered output. If the section heading ever changes, the script skips silently rather than crashing. TypeDoc just renders whatever's there.

docs/generate_api_readme.py, mkdocs.yml, package.json, typedoc.json, and .gitignore are updated. The 12 committed API_README.md files are removed.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud