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>

.github/workflows/python_docs.yml

@@ -7,6 +7,7 @@ on:
   push:
     branches:
       - master
+      - docs/mkdocs
       # Disabled until docs support versioning per branch/release
       # - develop
   release:

CHANGELOG.md

@@ -1,8 +1,10 @@
-.# Changelog
+# Changelog
+
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+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).
+
+
 
 ## [Unreleased]
 

CONTRIBUTING.md

@@ -42,7 +42,8 @@ GitHub provides additional document on [forking a repository](https://help.githu
 You might find useful to run both the documentation website and the API reference locally while contributing:
 
 * **API reference**: `make docs-api-local`
-* **Docs website**: `make dev-docs` to install deps, and `make docs-local` to run it thereafter
+* **Docs website**: `make docs-local`
+	- If you prefer using Docker: `make docs-local-docker`
 
 ### Conventions
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: target dev dev-docs format lint test coverage-html pr  build build-docs build-docs-api build-docs-website
+.PHONY: target dev format lint test coverage-html pr  build build-docs build-docs-api build-docs-website
 .PHONY: docs-local docs-api-local security-baseline complexity-baseline release-prod release-test release
 
 target:
@@ -9,9 +9,6 @@ dev:
 	poetry install --extras "pydantic"
 	pre-commit install
 
-dev-docs:
-	cd docs && yarn install
-
 format:
 	poetry run isort -rc aws_lambda_powertools tests
 	poetry run black aws_lambda_powertools tests
@@ -40,13 +37,17 @@ build-docs-api: dev
 	mv -f dist/api/aws_lambda_powertools/* dist/api/
 	rm -rf dist/api/aws_lambda_powertools
 
-build-docs-website: dev-docs
+build-docs-website: dev
 	mkdir -p dist
-	cd docs && yarn build
-	cp -R docs/public/* dist/
+	poetry run mkdocs build
+	cp -R site/* dist/
+
+docs-local:
+	poetry run mkdocs serve
 
-docs-local: dev-docs
-	cd docs && yarn start
+docs-local-docker:
+	docker build -t squidfunk/mkdocs-material ./docs/
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
 
 docs-api-local:
 	poetry run pdoc --http : aws_lambda_powertools

docs/Dockerfile

@@ -0,0 +1,2 @@
+FROM squidfunk/mkdocs-material
+RUN pip install mkdocs-git-revision-date-plugin

docs/changelog.md

@@ -0,0 +1,2 @@
+[comment]: <> (Includes Changelog content entire file as a snippet)
+--8<-- "CHANGELOG.md"