Merge pull request #36 from arandito/add-top-level-docs

Generate top-level and individual API reference docs for all SDK clients

Author: arandito

.gitignore

@@ -0,0 +1,19 @@
+# macOS system files
+.DS_Store
+
+# MkDocs build artifacts
+site/
+docs/SUMMARY.md
+docs/clients/
+**/docs/client/
+
+# Virtual environments
+.venv
+venv
+
+# Caches
+__pycache__/
+.ruff_cache/
+
+# Dependency lock file for uv
+uv.lock

CONTRIBUTING.md

@@ -56,4 +56,4 @@ If you discover a potential security issue in this project we ask that you notif
 
 ## Licensing
 
-See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+See the [LICENSE](https://github.com/awslabs/aws-sdk-python/blob/develop/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.

Makefile

@@ -0,0 +1,25 @@
+DOCS_PORT ?= 8000
+PYTHON_VERSION := 3.12
+
+.PHONY: docs docs-serve docs-clean docs-install venv
+
+venv:
+	uv venv --python $(PYTHON_VERSION)
+
+docs-install: venv
+	uv pip install -r requirements-docs.in
+	uv pip install -e clients/*
+
+docs-clean:
+	rm -rf site docs/clients docs/SUMMARY.md
+
+docs-generate:
+	uv run python scripts/docs/generate_all_doc_stubs.py
+	uv run python scripts/docs/generate_nav.py
+
+docs: docs-generate
+	uv run mkdocs build
+
+docs-serve:
+	@[ -d site ] || $(MAKE) docs
+	uv run python -m http.server $(DOCS_PORT) --bind 127.0.0.1 --directory site

README.md

@@ -31,7 +31,7 @@ This is the preferred mechanism to give feedback so that other users can engage
 
 ## Security
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+See [CONTRIBUTING](https://github.com/awslabs/aws-sdk-python/blob/develop/CONTRIBUTING.md#security-issue-notifications) for more information.
 
 ## License
 

clients/aws-sdk-bedrock-runtime/Makefile

@@ -0,0 +1,25 @@
+DOCS_PORT ?= 8000
+CLIENT_DIR := src/aws_sdk_bedrock_runtime
+DOCS_OUTPUT_DIR := docs/client
+PYTHON_VERSION := 3.12
+
+.PHONY: docs docs-serve docs-clean docs-install venv
+
+venv:
+	uv venv --python $(PYTHON_VERSION)
+
+docs-install: venv
+	uv sync --group docs
+
+docs-clean:
+	rm -rf site $(DOCS_OUTPUT_DIR)
+
+docs-generate:
+	uv run python scripts/docs/generate_doc_stubs.py -c $(CLIENT_DIR) -o $(DOCS_OUTPUT_DIR)
+
+docs: docs-generate
+	uv run mkdocs build
+
+docs-serve:
+	@[ -d site ] || $(MAKE) docs
+	uv run python -m http.server $(DOCS_PORT) --bind 127.0.0.1 --directory site

clients/aws-sdk-bedrock-runtime/docs/README.md

@@ -0,0 +1,18 @@
+## Generating Client Documentation
+
+Material for MkDocs is used for documentation. You can generate the documentation HTML
+for this client locally with the following:
+
+```bash
+# Install documentation dependencies
+make docs-install
+
+# Serve documentation locally
+make docs-serve
+
+# OR build static HTML documentation
+make docs
+
+# Clean docs artifacts
+make docs-clean
+```

clients/aws-sdk-bedrock-runtime/docs/hooks/copyright.py

@@ -0,0 +1,6 @@
+from datetime import datetime
+
+
+def on_config(config, **kwargs):
+    config.copyright = f"Copyright © {datetime.now().year}, Amazon Web Services, Inc"
+    return config

clients/aws-sdk-bedrock-runtime/docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

clients/aws-sdk-bedrock-runtime/docs/stylesheets/extra.css

@@ -0,0 +1,9 @@
+/* Custom breadcrumb styling */
+.breadcrumb {
+    font-size: 0.85em;
+    color: var(--md-default-fg-color--light);
+}
+
+p:has(span.breadcrumb) {
+margin-top: 0;
+}

clients/aws-sdk-bedrock-runtime/mkdocs.yml

@@ -0,0 +1,96 @@
+site_name: AWS SDK for Python - Bedrock Runtime
+site_description: Documentation for AWS Bedrock Runtime Client
+
+repo_name: awslabs/aws-sdk-python
+repo_url: https://github.com/awslabs/aws-sdk-python
+
+exclude_docs: |
+  README.md
+
+hooks:
+  - docs/hooks/copyright.py
+
+theme:
+  name: material
+  favicon: ""
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      scheme: default
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+      primary: white
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+      primary: white
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+      primary: black
+  features:
+    - navigation.indexes
+    - navigation.instant
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: false
+            show_signature: true
+            show_signature_annotations: true
+            show_root_heading: true
+            show_root_full_path: false
+            show_object_full_path: false
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            show_if_no_docstring: true
+            show_category_heading: true
+            group_by_category: true
+            separate_signature: true
+            signature_crossrefs: true
+            filters:
+              - "!^_"
+              - "!^deserialize"
+              - "!^serialize"
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences
+  - admonition
+  - def_list
+  - toc:
+      permalink: true
+      toc_depth: 3
+
+nav:
+  - Overview: index.md
+  - Client: client/index.md
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/awslabs/aws-sdk-python
+
+extra_css:
+  - stylesheets/extra.css
+
+validation:
+  nav:
+    omitted_files: ignore