New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(docs): generate docs from docstrings #5131

Open

JP-Ellis wants to merge 632 commits into aws-powertools:develop from JP-Ellis:feat/generate-docs-from-docstrings

+12,734 −3,894

JP-Ellis commented Sep 5, 2024

Issue number: #5125

Summary

Changes

This is a fairly major change to the docs and generates documentation for all public methods, attributes and variables in AWS Powertools.

This is achieved using mkdocstrings, which replaces instances of

::: some.module.path

with the documentation of the specified module.

As a side effect of generating the documentation, an objects.inv file is also generated.

From a quick purview of the generated docs, they seem pretty good as the underlying code appears well documented; however, this probably needs to be double checked. Especially for cases where the Numpy docstring style is not being followed which may result in errors generating the docs.

User experience

There is no change to the usage of AWS Powertools.

There will be a significant change to the documentation in that the classes/functions/variables will be made public. Most editors would already be presenting this information to developers already, but this just makes it discoverable online.

The main benefit here is that other docs which want to refer to a specific class or function from AWS Powertools can now do so using the objects.inv file generated.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

Meet tenets criteria
I have performed a self-review of this change
Changes have been tested
- I have tested the generation of docs locally, but I am not familiar with the rest of your pipeline for the documentation.
Changes are documented
- As these are changes to the documentation itself, they should be self-evident to the end users
- I would be happy to be pointed to most appropriate for the documentation on the documentation
PR title follows conventional commit semantics

Acknowledgment

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

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

dependabot bot and others added 30 commits

July 12, 2024 08:09


          chore(deps-dev): bump cfn-lint from 1.5.3 to 1.6.0 (aws-powertools#4747)

125186d

Bumps [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) from 1.5.3 to 1.6.0.
- [Release notes](https://github.com/aws-cloudformation/cfn-lint/releases)
- [Changelog](https://github.com/aws-cloudformation/cfn-lint/blob/main/CHANGELOG.md)
- [Commits](aws-cloudformation/cfn-lint@v1.5.3...v1.6.0)

---
updated-dependencies:
- dependency-name: cfn-lint
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): new pre-release 2.41.1a0 (aws-powertools#4749)

ee5cafa

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(ci): changelog rebuild (aws-powertools#4742)

43d1376

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps-dev): bump cfn-lint from 1.6.0 to 1.6.1 (aws-powertools#4751)

c0453f1

Bumps [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) from 1.6.0 to 1.6.1.
- [Release notes](https://github.com/aws-cloudformation/cfn-lint/releases)
- [Changelog](https://github.com/aws-cloudformation/cfn-lint/blob/main/CHANGELOG.md)
- [Commits](aws-cloudformation/cfn-lint@v1.6.0...v1.6.1)

---
updated-dependencies:
- dependency-name: cfn-lint
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps): bump actions/dependency-review-action from 4.3.3 to 4.3.4 (

d05436b

aws-powertools#4753)

Bumps [actions/dependency-review-action](https://github.com/actions/dependency-review-action) from 4.3.3 to 4.3.4.
- [Release notes](https://github.com/actions/dependency-review-action/releases)
- [Commits](actions/dependency-review-action@72eb03d...5a2ce3f)

---
updated-dependencies:
- dependency-name: actions/dependency-review-action
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): new pre-release 2.41.1a1 (aws-powertools#4756)

9fc7669

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          feat(event_handler): add OpenAPI extensions (aws-powertools#4703)

b8b4632

* Initial commit OpenAPI Extensions

* Polishing the PR with best practicies - Comments

* Polishing the PR with best practicies - Tests

* Polishing the PR with best practicies - make pydanticv2 happy

* Polishing the PR with best practicies - using model_validator to be more specific

* Temporary mypy disabling

* Make mypy happy?

* Make mypy happy?

* Polishing the PR with best practicies - adding e2e tests

* Adding docstring

* Adding documentation

* Addressing Simon's feedback

* Addressing Simon's feedback

* Addressing Simon's feedback

* Adding more tests

* Adding more tests

* Adding more tests


          chore(ci): new pre-release 2.41.1a2 (aws-powertools#4758)

fe6ad7e

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps-dev): bump cdklabs-generative-ai-cdk-constructs from 0.1.2…

3ed9ff6

…07 to 0.1.211 (aws-powertools#4760)

chore(deps-dev): bump cdklabs-generative-ai-cdk-constructs

Bumps [cdklabs-generative-ai-cdk-constructs](https://github.com/awslabs/generative-ai-cdk-constructs) from 0.1.207 to 0.1.211.
- [Release notes](https://github.com/awslabs/generative-ai-cdk-constructs/releases)
- [Changelog](https://github.com/awslabs/generative-ai-cdk-constructs/blob/main/CHANGELOG.md)
- [Commits](awslabs/generative-ai-cdk-constructs@v0.1.207...v0.1.211)

---
updated-dependencies:
- dependency-name: cdklabs-generative-ai-cdk-constructs
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): new pre-release 2.41.1a3 (aws-powertools#4766)

238d7a1

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps-dev): bump sentry-sdk from 2.9.0 to 2.10.0 (aws-powertools…

c135151

…#4763)

Bumps [sentry-sdk](https://github.com/getsentry/sentry-python) from 2.9.0 to 2.10.0.
- [Release notes](https://github.com/getsentry/sentry-python/releases)
- [Changelog](https://github.com/getsentry/sentry-python/blob/master/CHANGELOG.md)
- [Commits](getsentry/sentry-python@2.9.0...2.10.0)

---
updated-dependencies:
- dependency-name: sentry-sdk
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump ruff from 0.5.1 to 0.5.2 (aws-powertools#4762)

aecf021

Bumps [ruff](https://github.com/astral-sh/ruff) from 0.5.1 to 0.5.2.
- [Release notes](https://github.com/astral-sh/ruff/releases)
- [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md)
- [Commits](astral-sh/ruff@0.5.1...0.5.2)

---
updated-dependencies:
- dependency-name: ruff
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump aws-cdk from 2.148.0 to 2.149.0 (aws-powertools…

841b525

…#4765)

Bumps [aws-cdk](https://github.com/aws/aws-cdk/tree/HEAD/packages/aws-cdk) from 2.148.0 to 2.149.0.
- [Release notes](https://github.com/aws/aws-cdk/releases)
- [Changelog](https://github.com/aws/aws-cdk/blob/main/CHANGELOG.v2.md)
- [Commits](https://github.com/aws/aws-cdk/commits/v2.149.0/packages/aws-cdk)

---
updated-dependencies:
- dependency-name: aws-cdk
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump mkdocs-material from 9.5.28 to 9.5.29 (aws-powe…

829cda2

…rtools#4764)

Bumps [mkdocs-material](https://github.com/squidfunk/mkdocs-material) from 9.5.28 to 9.5.29.
- [Release notes](https://github.com/squidfunk/mkdocs-material/releases)
- [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG)
- [Commits](squidfunk/mkdocs-material@9.5.28...9.5.29)

---
updated-dependencies:
- dependency-name: mkdocs-material
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): changelog rebuild (aws-powertools#4757)

5f41e44

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps-dev): bump cdklabs-generative-ai-cdk-constructs from 0.1.2…

fa95395

…11 to 0.1.212 (aws-powertools#4769)

chore(deps-dev): bump cdklabs-generative-ai-cdk-constructs

Bumps [cdklabs-generative-ai-cdk-constructs](https://github.com/awslabs/generative-ai-cdk-constructs) from 0.1.211 to 0.1.212.
- [Release notes](https://github.com/awslabs/generative-ai-cdk-constructs/releases)
- [Changelog](https://github.com/awslabs/generative-ai-cdk-constructs/blob/main/CHANGELOG.md)
- [Commits](awslabs/generative-ai-cdk-constructs@v0.1.211...v0.1.212)

---
updated-dependencies:
- dependency-name: cdklabs-generative-ai-cdk-constructs
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): new pre-release 2.41.1a4 (aws-powertools#4772)

0f155aa

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps): bump datadog-lambda from 6.96.0 to 6.97.0 (aws-powertool…

…s#4770)

Bumps [datadog-lambda](https://github.com/DataDog/datadog-lambda-python) from 6.96.0 to 6.97.0.
- [Release notes](https://github.com/DataDog/datadog-lambda-python/releases)
- [Commits](DataDog/datadog-lambda-python@v6.96.0...v6.97.0)

---
updated-dependencies:
- dependency-name: datadog-lambda
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): changelog rebuild (aws-powertools#4768)

b1c0532

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(ci): new pre-release 2.41.1a5 (aws-powertools#4777)

9a2a6cd


          chore(deps): bump github.com/aws/aws-sdk-go-v2/config from 1.27.26 to…

87a4203

… 1.27.27 in /layer/scripts/layer-balancer in the layer-balancer group (aws-powertools#4779)

chore(deps): bump github.com/aws/aws-sdk-go-v2/config

Bumps the layer-balancer group in /layer/scripts/layer-balancer with 1 update: [github.com/aws/aws-sdk-go-v2/config](https://github.com/aws/aws-sdk-go-v2).


Updates `github.com/aws/aws-sdk-go-v2/config` from 1.27.26 to 1.27.27
- [Release notes](https://github.com/aws/aws-sdk-go-v2/releases)
- [Commits](aws/aws-sdk-go-v2@config/v1.27.26...config/v1.27.27)

---
updated-dependencies:
- dependency-name: github.com/aws/aws-sdk-go-v2/config
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: layer-balancer
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump pytest-asyncio from 0.23.7 to 0.23.8 (aws-power…

e53b521

…tools#4776)

Bumps [pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio) from 0.23.7 to 0.23.8.
- [Release notes](https://github.com/pytest-dev/pytest-asyncio/releases)
- [Commits](pytest-dev/pytest-asyncio@v0.23.7...v0.23.8)

---
updated-dependencies:
- dependency-name: pytest-asyncio
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump cfn-lint from 1.6.1 to 1.8.1 (aws-powertools#4780)

9cbc162

Bumps [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) from 1.6.1 to 1.8.1.
- [Release notes](https://github.com/aws-cloudformation/cfn-lint/releases)
- [Changelog](https://github.com/aws-cloudformation/cfn-lint/blob/main/CHANGELOG.md)
- [Commits](aws-cloudformation/cfn-lint@v1.6.1...v1.8.1)

---
updated-dependencies:
- dependency-name: cfn-lint
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): new pre-release 2.41.1a6 (aws-powertools#4783)

3c62340

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(ci): changelog rebuild (aws-powertools#4778)

df3bbf1

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps-dev): bump ruff from 0.5.2 to 0.5.3 (aws-powertools#4781)

d178865

Bumps [ruff](https://github.com/astral-sh/ruff) from 0.5.2 to 0.5.3.
- [Release notes](https://github.com/astral-sh/ruff/releases)
- [Changelog](https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md)
- [Commits](astral-sh/ruff@0.5.2...0.5.3)

---
updated-dependencies:
- dependency-name: ruff
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          fix(idempotency): ensure in_progress_expiration field is set on Lambd…

ab5f7d8

…a timeout. (aws-powertools#4773)

* fix(idempotency): fix timeout bug from aws-powertools#4759

* Adding comment

* Adding comment

---------

Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(ci): changelog rebuild (aws-powertools#4784)

09d6c84

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>


          chore(deps): bump aws-actions/closed-issue-message from 8b63243121934…

807a56e

…76beecf11f8e8539d73a3553bf4 to 80edfc24bdf1283400eb04d20a8a605ae8bf7d48 (aws-powertools#4786)

chore(deps): bump aws-actions/closed-issue-message

Bumps [aws-actions/closed-issue-message](https://github.com/aws-actions/closed-issue-message) from 8b6324312193476beecf11f8e8539d73a3553bf4 to 80edfc24bdf1283400eb04d20a8a605ae8bf7d48.
- [Commits](aws-actions/closed-issue-message@8b63243...80edfc2)

---
updated-dependencies:
- dependency-name: aws-actions/closed-issue-message
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump mypy-boto3-secretsmanager from 1.34.128 to 1.34…

6377a3b

….145 in the boto-typing group (aws-powertools#4787)

chore(deps-dev): bump mypy-boto3-secretsmanager in the boto-typing group

Bumps the boto-typing group with 1 update: [mypy-boto3-secretsmanager](https://github.com/youtype/mypy_boto3_builder).


Updates `mypy-boto3-secretsmanager` from 1.34.128 to 1.34.145
- [Release notes](https://github.com/youtype/mypy_boto3_builder/releases)
- [Commits](https://github.com/youtype/mypy_boto3_builder/commits)

---
updated-dependencies:
- dependency-name: mypy-boto3-secretsmanager
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: boto-typing
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

dependabot bot and others added 13 commits

September 4, 2024 09:02


          chore(deps): bump the layer-balancer group in /layer/scripts/layer-ba…

e4341df

…lancer with 3 updates (aws-powertools#5114)

chore(deps): bump the layer-balancer group

Bumps the layer-balancer group in /layer/scripts/layer-balancer with 3 updates: [github.com/aws/aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2), [github.com/aws/aws-sdk-go-v2/config](https://github.com/aws/aws-sdk-go-v2) and [github.com/aws/aws-sdk-go-v2/service/lambda](https://github.com/aws/aws-sdk-go-v2).


Updates `github.com/aws/aws-sdk-go-v2` from 1.30.4 to 1.30.5
- [Release notes](https://github.com/aws/aws-sdk-go-v2/releases)
- [Commits](aws/aws-sdk-go-v2@v1.30.4...v1.30.5)

Updates `github.com/aws/aws-sdk-go-v2/config` from 1.27.31 to 1.27.32
- [Release notes](https://github.com/aws/aws-sdk-go-v2/releases)
- [Commits](aws/aws-sdk-go-v2@config/v1.27.31...config/v1.27.32)

Updates `github.com/aws/aws-sdk-go-v2/service/lambda` from 1.58.1 to 1.58.2
- [Release notes](https://github.com/aws/aws-sdk-go-v2/releases)
- [Commits](aws/aws-sdk-go-v2@service/s3/v1.58.1...service/s3/v1.58.2)

---
updated-dependencies:
- dependency-name: github.com/aws/aws-sdk-go-v2
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: layer-balancer
- dependency-name: github.com/aws/aws-sdk-go-v2/config
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: layer-balancer
- dependency-name: github.com/aws/aws-sdk-go-v2/service/lambda
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: layer-balancer
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps): bump pypa/gh-action-pypi-publish from 1.10.0 to 1.10.1 (a…

b35b1a5

…ws-powertools#5115)

Bumps [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) from 1.10.0 to 1.10.1.
- [Release notes](https://github.com/pypa/gh-action-pypi-publish/releases)
- [Commits](pypa/gh-action-pypi-publish@8a08d61...0ab0b79)

---
updated-dependencies:
- dependency-name: pypa/gh-action-pypi-publish
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(deps-dev): bump types-redis from 4.6.0.20240819 to 4.6.0.202409…

9fdd487

…03 (aws-powertools#5116)

Bumps [types-redis](https://github.com/python/typeshed) from 4.6.0.20240819 to 4.6.0.20240903.
- [Commits](https://github.com/python/typeshed/commits)

---
updated-dependencies:
- dependency-name: types-redis
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(deps-dev): bump aws-cdk-aws-lambda-python-alpha from 2.154.1a0 …

a398e1c

…to 2.155.0a0 (aws-powertools#5117)

chore(deps-dev): bump aws-cdk-aws-lambda-python-alpha

Bumps [aws-cdk-aws-lambda-python-alpha](https://github.com/aws/aws-cdk) from 2.154.1a0 to 2.155.0a0.
- [Release notes](https://github.com/aws/aws-cdk/releases)
- [Changelog](https://github.com/aws/aws-cdk/blob/main/CHANGELOG.v2.md)
- [Commits](https://github.com/aws/aws-cdk/commits)

---
updated-dependencies:
- dependency-name: aws-cdk-aws-lambda-python-alpha
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(deps): bump cryptography from 42.0.8 to 43.0.1 (aws-powertools#…

00e4552

…5119)

Bumps [cryptography](https://github.com/pyca/cryptography) from 42.0.8 to 43.0.1.
- [Changelog](https://github.com/pyca/cryptography/blob/main/CHANGELOG.rst)
- [Commits](pyca/cryptography@42.0.8...43.0.1)

---
updated-dependencies:
- dependency-name: cryptography
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(deps-dev): bump cfn-lint from 1.11.1 to 1.12.1 (aws-powertools#…

5c6c850

…5118)

Bumps [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) from 1.11.1 to 1.12.1.
- [Release notes](https://github.com/aws-cloudformation/cfn-lint/releases)
- [Changelog](https://github.com/aws-cloudformation/cfn-lint/blob/main/CHANGELOG.md)
- [Commits](aws-cloudformation/cfn-lint@v1.11.1...v1.12.1)

---
updated-dependencies:
- dependency-name: cfn-lint
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps-dev): bump mypy-boto3-logs from 1.35.10 to 1.35.12 in the …

7de9cf8

…boto-typing group (aws-powertools#5121)

chore(deps-dev): bump mypy-boto3-logs in the boto-typing group

Bumps the boto-typing group with 1 update: [mypy-boto3-logs](https://github.com/youtype/mypy_boto3_builder).


Updates `mypy-boto3-logs` from 1.35.10 to 1.35.12
- [Release notes](https://github.com/youtype/mypy_boto3_builder/releases)
- [Commits](https://github.com/youtype/mypy_boto3_builder/commits)

---
updated-dependencies:
- dependency-name: mypy-boto3-logs
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: boto-typing
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(deps): bump the layer-balancer group in /layer/scripts/layer-ba…

807eb89

…lancer with 2 updates (aws-powertools#5124)

chore(deps): bump the layer-balancer group

Bumps the layer-balancer group in /layer/scripts/layer-balancer with 2 updates: [github.com/aws/aws-sdk-go-v2/config](https://github.com/aws/aws-sdk-go-v2) and [github.com/aws/aws-sdk-go-v2/service/lambda](https://github.com/aws/aws-sdk-go-v2).


Updates `github.com/aws/aws-sdk-go-v2/config` from 1.27.32 to 1.27.33
- [Release notes](https://github.com/aws/aws-sdk-go-v2/releases)
- [Commits](aws/aws-sdk-go-v2@config/v1.27.32...config/v1.27.33)

Updates `github.com/aws/aws-sdk-go-v2/service/lambda` from 1.58.2 to 1.58.3
- [Release notes](https://github.com/aws/aws-sdk-go-v2/releases)
- [Commits](aws/aws-sdk-go-v2@service/s3/v1.58.2...service/s3/v1.58.3)

---
updated-dependencies:
- dependency-name: github.com/aws/aws-sdk-go-v2/config
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: layer-balancer
- dependency-name: github.com/aws/aws-sdk-go-v2/service/lambda
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: layer-balancer
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(deps-dev): bump cdklabs-generative-ai-cdk-constructs from 0.1.2…

42bc105

…62 to 0.1.263 (aws-powertools#5122)

chore(deps-dev): bump cdklabs-generative-ai-cdk-constructs

Bumps [cdklabs-generative-ai-cdk-constructs](https://github.com/awslabs/generative-ai-cdk-constructs) from 0.1.262 to 0.1.263.
- [Release notes](https://github.com/awslabs/generative-ai-cdk-constructs/releases)
- [Changelog](https://github.com/awslabs/generative-ai-cdk-constructs/blob/main/CHANGELOG.md)
- [Commits](awslabs/generative-ai-cdk-constructs@v0.1.262...v0.1.263)

---
updated-dependencies:
- dependency-name: cdklabs-generative-ai-cdk-constructs
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>


          chore(ci): changelog rebuild (aws-powertools#5120)

b3aa735

Co-authored-by: Powertools for AWS Lambda (Python) bot <151832416+aws-powertools-bot@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(deps-dev): bump cfn-lint from 1.12.1 to 1.12.3 (aws-powertools#…

fa75696

…5126)

Bumps [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) from 1.12.1 to 1.12.3.
- [Release notes](https://github.com/aws-cloudformation/cfn-lint/releases)
- [Changelog](https://github.com/aws-cloudformation/cfn-lint/blob/main/CHANGELOG.md)
- [Commits](aws-cloudformation/cfn-lint@v1.12.1...v1.12.3)

---
updated-dependencies:
- dependency-name: cfn-lint
  dependency-type: direct:development
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          chore(ci): allow sar beta app (aws-powertools#5109)

c2a2f86

Co-authored-by: Leandro Damascena <lcdama@amazon.pt>


          feat(docs): generate docs from docstrings

496379b

This is a fairly major change to the docs and generates documentation for all
public methods, attributes and variables in AWS Powertools.

This is achieved using `mkdocstrings`, which replaces instances of

```markdown
::: some.module.path
```

with the documentation of the specified module.

As a side effect of generating the documentation, an `objects.inv` file is also
generated.

From a quick purview of the generated docs, they seem pretty good as the
underlying code appears well documented; however, this probably needs to be
double checked. Especially for cases where the Numpy docstring style is not
being followed which may result in errors generating the docs.

Ref: aws-powertools#5125
Signed-off-by: JP-Ellis <josh@jpellis.me>

JP-Ellis requested a review from a team as a code owner

September 5, 2024 22:40

boring-cyborg bot added documentation internal labels

boring-cyborg bot commented Sep 5, 2024

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

pull-request-size bot added the size/L label

sonarqubecloud bot commented Sep 5, 2024

Quality Gate passed

Issues
0 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 SonarCloud

github-actions bot added feature and removed documentation internal labels

Contributor

leandrodamascena commented Sep 9, 2024

Hey @JP-Ellis thanks for working in this PR and creating a reproduicle outcome from what we can expect.

Let me split down my feedback to make easy we agree on the next steps.

pdoc3 vs mkdocstrings

We already have an API documentation created by pdoc3, which works well. Personally, I like it; however, I see much more value in using mkdocstrings because it integrates seamlessly with our documentation and offers greater potential to utilize features from MkDocs, which is fantastic. In addition, we already have an issue opened for this migration, which is a great step forward to agree with this kind of work.

Testing this PR

2 - I tested this PR locally and I was able to create the objects.inv file and render the new API tab, which is great to see this working and how it looks like.

Current limitations/problems

3 - Even if we agreeing to migrate from pdoc3 to mkdocstrings, I see some problems in accepting this PR as it is. To move forward, we need to rethink how to do this. In this PR, you are adding 55 new files and marking some to be ignored by markdown lint, which may have some undesirable effects. Also, I admit that our codebase is far from being suitable for mkdocstrings to render this perfectly - or even good. Here are some examples:

We should not render these attributes

The code is completely broken here

We should not have these special characters in the examples

Links without href tag

Making a smooth transition

I'm thinking about making a smooth transition from pdoc3 to mkdocstrings and splitting it by utility, rather than all utilities at once. I suggest this because we'll need to change a lot in our docstrings, comments, and others to have documentation that is actually usable by customers. Otherwise, we'll just introduce a new section that doesn't have much value and may generate doubts about how to use it.

Enabling a new Ruff rule

5 - We can use this opportunity to progressively enable a new Ruff linter rule: https://docs.astral.sh/ruff/rules/#pydocstyle-d. We didn't enable that because our docstrings and comments need to be revamped.

Next steps

So, based on what I explained before, I suggest the next steps are:

1 - Modify this PR to add just one utility and make all the changes we need to make to the mkdocstrings + docstrings configuration. I suggest we start with BatchProcessing as the codebase is not complex and we can do an excellent job on it that will serve as a base for the others.
2 - Enable the Ruff D rule on this PR and see which files Ruff complains about.
3 - Publish the first version with this new change and see how this looks like.

Please let me know what you think and if you would like to make these changes and go through some back-and-forth review process. If you don't have time to do this —we know everyone is very busy— I can handle it and ping you for reviews and feedback. Please let me know your thoughts.

Again, thanks a lot for kicking out this to make our documentation even better.

leandrodamascena added the on-hold label

leandrodamascena requested changes

View reviewed changes

Contributor

leandrodamascena left a comment

Leaving a comment to Request Changes.

leandrodamascena linked an issue

that may be closed by this pull request

Docs: Addition of docs inventory (objects.inv) #5125

Open

1 task

Author

JP-Ellis commented Sep 9, 2024

Amazing feedback!

I should have made it clear at the start that this is meant to be a first proof-of-concept and step towards MkDocstrings. I didn't want to invest too much time in case this wasn't going to be adopted. I'm glad to hear this is something you are keen on!

To answer some of your more specific feedback.

pdoc3 vs mkdocstrings

We already have an API documentation [and] we already have an issue opened for [migrating to MkDocs]

I'll be honest, I completely missed that. But I'm glad to hear this was in the pipeline already!

In this PR, you are adding 55 new files and marking some to be ignored by markdown lint, which may have some undesirable effects.

Completely agree. When I personally use this, I actually create a small Python scripts that is invoked by Mkdocs to automatically generate the Markdown files on-the-fly. There are a couple of pros and cons:

Pro: The Markdown files are guaranteed to correspond to the Python files
Pro: No need to commit a large number of mostly-the-same Markdown files
Con: It may seem a bit 'magical' to someone unfamiliar
Con: It doesn't allow for customisation of the Markdown file on a per-file basis (I would say that for API docs, this is typically not a big issue)
Con: It adds yet another dependency, though only for building the docs.

Also, I admit that our codebase is far from being suitable for mkdocstrings to render this perfectly [...] we'll just introduce a new section that doesn't have much value and may generate doubts about how to use it.

Yeah, that's completely fair. A per-utility approach would certainly be possible. Since you already have the pdoc3 docs up, you could also put a disclaimer during the transition to the effect of

Note

The below docs are in the process of being transitioned and may contain some formatting issues.

We can use this opportunity to progressively enable a new Ruff linter rule: https://docs.astral.sh/ruff/rules/#pydocstyle-d. We didn't enable that because our docstrings and comments need to be revamped.

Absolutely a fantastic thing to add. Just be aware that Ruff doesn't necessarily enforce all docstring rules all the time as it tries to be smart about which lints are applicable to which rules. As a concrete example in repos I maintain, Ruff will detect if there is a mismatch between the args documented and the args in the function; but it will not raise a lint if the docstring has no args at all. This can be problematic if the args are in fact documented but in a style which Ruff did not expect.

With the pace of Ruff's development, this may have changed over the past months, but that is something to be aware of.

Modify this PR to add just one utility and make all the changes we need to make to the mkdocstrings + docstrings configuration. I suggest we start with BatchProcessing as the codebase is not complex and we can do an excellent job on it that will serve as a base for the others.

Enable the Ruff D rule on this PR and see which files Ruff complains about.

Publish the first version with this new change and see how this looks like.

Sounds good! I won't get much time this week to contribute, but hopefully this weekend or next week I should get a bit of time :)

Contributor

leandrodamascena commented Sep 10, 2024

Hey @JP-Ellis! Thanks for the feedback and clarifying things about this PoC. I am writing additional feedback based on your answers.

Completely agree. When I personally use this, I actually create a small Python scripts that is invoked by Mkdocs to automatically generate the Markdown files on-the-fly. There are a couple of pros and cons:

Yes, we should avoid doing this. My observation about the number of files is because it makes it difficult to review the PR and we can lose attention with too many files. That's why I suggested dividing this into small PRs by utility, which will make our work easier.

Yeah, that's completely fair. A per-utility approach would certainly be possible. Since you already have the pdoc3 docs up, you could also put a disclaimer during the transition to the effect of

Perfect, this is a really good idea.

Absolutely a fantastic thing to add. Just be aware that Ruff doesn't necessarily enforce all docstring rules all the time as it tries to be smart about which lints are applicable to which rules. As a concrete example in repos I maintain, Ruff will detect if there is a mismatch between the args documented and the args in the function; but it will not raise a lint if the docstring has no args at all. This can be problematic if the args are in fact documented but in a style which Ruff did not expect.

With the pace of Ruff's development, this may have changed over the past months, but that is something to be aware of.

Hmmm, I didn't know that. I'll spend some time checking this out and see what limitations/caveats we should be aware of and deal with "manually" when doing this work.

Modify this PR to add just one utility and make all the changes we need to make to the mkdocstrings + docstrings configuration. I suggest we start with BatchProcessing as the codebase is not complex and we can do an excellent job on it that will serve as a base for the others.

Enable the Ruff D rule on this PR and see which files Ruff complains about.

Publish the first version with this new change and see how this looks like.

Sounds good! I won't get much time this week to contribute, but hopefully this weekend or next week I should get a bit of time :)

Perfect! Take your time, no rush at all and will be amazing to make this change and improve our documentation.

Thanks for taking the time to do this and let's make it happen 😄

leandrodamascena changed the base branch from v2 to develop

October 5, 2024 22:20

boring-cyborg bot added the github-actions label

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature github-actions on-hold size/L