feat(docs): generate docs from docstrings

JP-Ellis · JP-Ellis · commit 496379b35824 · 2024-09-06T08:30:15.000+10:00
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: #5125 Signed-off-by: JP-Ellis <josh@jpellis.me>
diff --git a/.gitignore b/.gitignore
@@ -301,7 +301,7 @@ TMP_CHANGELOG.md
 docs/.cache/
 docs/public
 node_modules
-api/
+# api/
 site/
 !404.html
 !docs/overrides/*.html
diff --git a/.markdownlintignore b/.markdownlintignore
@@ -1,2 +1,3 @@
 docs/core/metrics/index.md
 includes/abbreviations.md
+docs/api/**
diff --git a/docs/api/event_handler.md b/docs/api/event_handler.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler
diff --git a/docs/api/event_handler/api_gateway.md b/docs/api/event_handler/api_gateway.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.api_gateway
diff --git a/docs/api/event_handler/appsync.md b/docs/api/event_handler/appsync.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.appsync
diff --git a/docs/api/event_handler/bedrock_agent.md b/docs/api/event_handler/bedrock_agent.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.bedrock_agent
diff --git a/docs/api/event_handler/content_types.md b/docs/api/event_handler/content_types.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.content_types
diff --git a/docs/api/event_handler/exceptions.md b/docs/api/event_handler/exceptions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.exceptions
diff --git a/docs/api/event_handler/lambda_function_url.md b/docs/api/event_handler/lambda_function_url.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.lambda_function_url
diff --git a/docs/api/event_handler/router.md b/docs/api/event_handler/router.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.router
diff --git a/docs/api/event_handler/types.md b/docs/api/event_handler/types.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.types
diff --git a/docs/api/event_handler/util.md b/docs/api/event_handler/util.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.util
diff --git a/docs/api/event_handler/vpc_lattice.md b/docs/api/event_handler/vpc_lattice.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.event_handler.vpc_lattice
diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.exceptions
diff --git a/docs/api/logging.md b/docs/api/logging.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging
diff --git a/docs/api/logging/constants.md b/docs/api/logging/constants.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.constants
diff --git a/docs/api/logging/correlation_paths.md b/docs/api/logging/correlation_paths.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.correlation_paths
diff --git a/docs/api/logging/exceptions.md b/docs/api/logging/exceptions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.exceptions
diff --git a/docs/api/logging/filters.md b/docs/api/logging/filters.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.filters
diff --git a/docs/api/logging/formatter.md b/docs/api/logging/formatter.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.formatter
diff --git a/docs/api/logging/lambda_context.md b/docs/api/logging/lambda_context.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.lambda_context
diff --git a/docs/api/logging/logger.md b/docs/api/logging/logger.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.logger
diff --git a/docs/api/logging/types.md b/docs/api/logging/types.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.types
diff --git a/docs/api/logging/utils.md b/docs/api/logging/utils.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.logging.utils
diff --git a/docs/api/metrics.md b/docs/api/metrics.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics
diff --git a/docs/api/metrics/base.md b/docs/api/metrics/base.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics.base
diff --git a/docs/api/metrics/exceptions.md b/docs/api/metrics/exceptions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics.exceptions
diff --git a/docs/api/metrics/functions.md b/docs/api/metrics/functions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics.functions
diff --git a/docs/api/metrics/metric.md b/docs/api/metrics/metric.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics.metric
diff --git a/docs/api/metrics/metrics.md b/docs/api/metrics/metrics.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics.metrics
diff --git a/docs/api/metrics/types.md b/docs/api/metrics/types.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.metrics.types
diff --git a/docs/api/middleware_factory.md b/docs/api/middleware_factory.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.middleware_factory
diff --git a/docs/api/middleware_factory/exceptions.md b/docs/api/middleware_factory/exceptions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.middleware_factory.exceptions
diff --git a/docs/api/middleware_factory/factory.md b/docs/api/middleware_factory/factory.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.middleware_factory.factory
diff --git a/docs/api/shared.md b/docs/api/shared.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared
diff --git a/docs/api/shared/cache_dict.md b/docs/api/shared/cache_dict.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.cache_dict
diff --git a/docs/api/shared/constants.md b/docs/api/shared/constants.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.constants
diff --git a/docs/api/shared/cookies.md b/docs/api/shared/cookies.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.cookies
diff --git a/docs/api/shared/functions.md b/docs/api/shared/functions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.functions
diff --git a/docs/api/shared/headers_serializer.md b/docs/api/shared/headers_serializer.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.headers_serializer
diff --git a/docs/api/shared/json_encoder.md b/docs/api/shared/json_encoder.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.json_encoder
diff --git a/docs/api/shared/lazy_import.md b/docs/api/shared/lazy_import.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.lazy_import
diff --git a/docs/api/shared/types.md b/docs/api/shared/types.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.types
diff --git a/docs/api/shared/user_agent.md b/docs/api/shared/user_agent.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.user_agent
diff --git a/docs/api/shared/version.md b/docs/api/shared/version.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.shared.version
diff --git a/docs/api/tracing.md b/docs/api/tracing.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.tracing
diff --git a/docs/api/tracing/base.md b/docs/api/tracing/base.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.tracing.base
diff --git a/docs/api/tracing/extensions.md b/docs/api/tracing/extensions.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.tracing.extensions
diff --git a/docs/api/tracing/tracer.md b/docs/api/tracing/tracer.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.tracing.tracer
diff --git a/docs/api/utilities.md b/docs/api/utilities.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.utilities
diff --git a/docs/api/utilities/serialization.md b/docs/api/utilities/serialization.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.utilities.serialization
diff --git a/docs/api/warnings.md b/docs/api/warnings.md
@@ -0,0 +1 @@
+::: aws_lambda_powertools.warnings
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -62,6 +62,64 @@ nav:
           #     - Overview: contributing/tracks/overview.md
           #     - Casual to regular contributor: contributing/tracks/casual_regular_contributor.md
           #     - Customer to advocate: contributing/tracks/customer_advocate.md
+  - API:
+    - Event Handler:
+      - api/event_handler.md
+      - api/event_handler/api_gateway.md
+      - api/event_handler/appsync.md
+      - api/event_handler/bedrock_agent.md
+      - api/event_handler/content_types.md
+      - api/event_handler/exceptions.md
+      - api/event_handler/lambda_function_url.md
+      - api/event_handler/router.md
+      - api/event_handler/types.md
+      - api/event_handler/util.md
+      - api/event_handler/vpc_lattice.md
+    - Exceptions: api/exceptions.md
+    - Logging:
+      - api/logging.md
+      - api/logging/constants.md
+      - api/logging/correlation_paths.md
+      - api/logging/exceptions.md
+      - api/logging/filters.md
+      - api/logging/formatter.md
+      - api/logging/lambda_context.md
+      - api/logging/logger.md
+      - api/logging/types.md
+      - api/logging/utils.md
+    - Metrics:
+      - api/metrics.md
+      - api/metrics/base.md
+      - api/metrics/exceptions.md
+      - api/metrics/functions.md
+      - api/metrics/metric.md
+      - api/metrics/metrics.md
+      - api/metrics/types.md
+    - Middleware Factory:
+      - api/middleware_factory.md
+      - api/middleware_factory/exceptions.md
+      - api/middleware_factory/factory.md
+    - Shared:
+      - api/shared.md
+      - api/shared/cache_dict.md
+      - api/shared/constants.md
+      - api/shared/cookies.md
+      - api/shared/functions.md
+      - api/shared/headers_serializer.md
+      - api/shared/json_encoder.md
+      - api/shared/lazy_import.md
+      - api/shared/types.md
+      - api/shared/user_agent.md
+      - api/shared/version.md
+    - Tracing:
+      - api/tracing.md
+      - api/tracing/base.md
+      - api/tracing/extensions.md
+      - api/tracing/tracer.md
+    - Utilities:
+      - api/utilities.md
+      - api/utilities/serialization.md
+    - Warnings: api/warnings.md
 
 theme:
   name: material
@@ -136,6 +194,43 @@ copyright: Copyright &copy; 2023 Amazon Web Services
 plugins:
   - git-revision-date
   - search
+  - mkdocstrings:
+      default_handler: python
+      enable_inventory: true
+      handlers:
+        python:
+          import:
+            - https://docs.python.org/3/objects.inv
+          options:
+            # General
+            allow_inspection: true
+            show_source: true
+            show_bases: true
+            # Headings
+            heading_level: 2
+            show_root_heading: false
+            show_root_toc_entry: true
+            show_root_full_path: true
+            show_root_members_full_path: false
+            show_object_full_path: false
+            show_category_heading: true
+            # Members
+            filters: ["!^_[^_]"]
+            group_by_category: true
+            show_submodules: false
+            # Docstrings
+            docstring_style: numpy
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: spacy
+            merge_init_into_class: true
+            show_if_no_docstring: true
+            # Signature
+            annotations_path: brief
+            show_signature: true
+            show_signature_annotations: true
+            separate_signature: true
+
 
 extra_css:
   - stylesheets/extra.css
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`docs/core/metrics/index.md`
`2`	`2`	`includes/abbreviations.md`
	`3`	`+docs/api/**`