Skip to content

Commit fc08062

Browse files
Alexheitorlessato-mcTom McCarthy
authored
docs: migrate documentation from Gatsby to MkDocs material (#279)
* fix whitespace * docs: add logger * docs: add middleware * docs: parameters * docs: batch * docs: typing * docs: validation * docs: dataclasses * docs: parser * docs: use mkdocs for website * docs: add docs branch to have live preview for the PR * docs: change color and adjust logo * docs: merged async and generator sections * docs: merged cloudwatch logs to tabs * docs: merged tabs * docs: remove highlight line markers * docs: add meta tags * docs: remove old docs folder * chore: typo in GetCfnTemplate Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/core/logger.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/core/logger.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/utilities/parameters.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/utilities/validation.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/utilities/validation.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/utilities/batch.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/core/tracer.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * remove code formatting from table headers * docs: increse max-width with extra css for readability * docs: add changes from review * docs: refactor doc targets, add docker build * docs: tabs naming for cloudwatch logs * docs: fix build-docs-website target * docs: enhance the visual aid for accessibility purposes * fix: syntax previously broken in last set of commits Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: async ops snippet completeness Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: screen real estate in home page. More effective use of table, and collapse verbose IAM example. Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: enable strict mode for broken links Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: merge Layer example to be more pragmatic Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: key features, getting started, clean non-essential Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: expand escape hatch, async, reuse examples Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: add getting started Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: add getting started, trim content, expand examples Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: wording on logger reuse Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: additional examples on formatting, order, etc. plus advanced navigation Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: typo on logging keys in FAQ Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: enable snippets extension; include changelog in the docs Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: docker no longer works with strict due to an issue upstream ref: mkdocs/mkdocs#2108 Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: add favicon Signed-off-by: heitorlessa <lessa@amazon.co.uk> * chore: consistency with metrics Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: docs revision date, smaller TOC, and footer copyright Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: enhanced navigation, trimmed content, added more examples Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: add openGraph and Twitter card, attempt 1 Signed-off-by: heitorlessa <lessa@amazon.co.uk> * Update docs/core/tracer.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * Update docs/core/tracer.md Co-authored-by: Tom McCarthy <tmac.se@gmail.com> * docs: set tabs for yaml/json to 2 spaces * fix: yaml indent for cfn * fix: formatting yaml cfn * fix: typo in features table Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: typo in features table, match sidebar Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: add built-in search Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: broken links Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: bring tenets up, clarify core vs general Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: broken links Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: contrast for layer IAM snippet Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: change extra dep to warning; wording Signed-off-by: heitorlessa <lessa@amazon.co.uk> * remove ... from cfn docs * fix: width; remove old comments Signed-off-by: heitorlessa <lessa@amazon.co.uk> * improv: add explicit section for LOG_EVENT Signed-off-by: heitorlessa <lessa@amazon.co.uk> * fix: highlight inject_lambda_context Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: add docker-based docs for dev Signed-off-by: heitorlessa <lessa@amazon.co.uk> * chore: copyright to 2021 Signed-off-by: heitorlessa <lessa@amazon.co.uk> * revert: search width Signed-off-by: heitorlessa <lessa@amazon.co.uk> * chore: Add higher res metrics image * chore: remove custom font; correct edit uri Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: record page view and search pattern Signed-off-by: heitorlessa <lessa@amazon.co.uk> * feat: add API reference Signed-off-by: heitorlessa <lessa@amazon.co.uk> Co-authored-by: Heitor Lessa <heitor.lessa@hotmail.com> Co-authored-by: Tom McCarthy <tmac.se@gmail.com> Co-authored-by: heitorlessa <lessa@amazon.co.uk> Co-authored-by: Tom McCarthy <thommcc@amazon.com>
1 parent bf66299 commit fc08062

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+3399
-21352
lines changed

‎.github/workflows/python_docs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ on:
77
push:
88
branches:
99
- master
10+
- docs/mkdocs
1011
# Disabled until docs support versioning per branch/release
1112
# - develop
1213
release:

‎CHANGELOG.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
.# Changelog
1+
# Changelog
2+
23
All notable changes to this project will be documented in this file.
34

4-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
5+
This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format for changes and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
68

79
## [Unreleased]
810

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ GitHub provides additional document on [forking a repository](https://help.githu
4242
You might find useful to run both the documentation website and the API reference locally while contributing:
4343

4444
* **API reference**: `make docs-api-local`
45-
* **Docs website**: `make dev-docs` to install deps, and `make docs-local` to run it thereafter
45+
* **Docs website**: `make docs-local`
46+
- If you prefer using Docker: `make docs-local-docker`
4647

4748
### Conventions
4849

‎Makefile‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: target dev dev-docs format lint test coverage-html pr build build-docs build-docs-api build-docs-website
1+
.PHONY: target dev format lint test coverage-html pr build build-docs build-docs-api build-docs-website
22
.PHONY: docs-local docs-api-local security-baseline complexity-baseline release-prod release-test release
33

44
target:
@@ -9,9 +9,6 @@ dev:
99
poetry install --extras "pydantic"
1010
pre-commit install
1111

12-
dev-docs:
13-
cd docs && yarn install
14-
1512
format:
1613
poetry run isort -rc aws_lambda_powertools tests
1714
poetry run black aws_lambda_powertools tests
@@ -40,13 +37,17 @@ build-docs-api: dev
4037
mv -f dist/api/aws_lambda_powertools/* dist/api/
4138
rm -rf dist/api/aws_lambda_powertools
4239

43-
build-docs-website: dev-docs
40+
build-docs-website: dev
4441
mkdir -p dist
45-
cd docs && yarn build
46-
cp -R docs/public/* dist/
42+
poetry run mkdocs build
43+
cp -R site/* dist/
44+
45+
docs-local:
46+
poetry run mkdocs serve
4747

48-
docs-local: dev-docs
49-
cd docs && yarn start
48+
docs-local-docker:
49+
docker build -t squidfunk/mkdocs-material ./docs/
50+
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
5051

5152
docs-api-local:
5253
poetry run pdoc --http : aws_lambda_powertools

‎docs/.prettierignore‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/.prettierrc‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/Dockerfile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
FROM squidfunk/mkdocs-material
2+
RUN pip install mkdocs-git-revision-date-plugin

‎docs/api/.gitkeep‎

Whitespace-only changes.

‎docs/changelog.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[comment]: <> (Includes Changelog content entire file as a snippet)
2+
--8<-- "CHANGELOG.md"

0 commit comments

Comments
 (0)