Merge branch 'develop'

* develop: chore: reformat changelog to follow KeepAChangelog standard (#50) docs: clarify logger debug sampling message improv: build docs on develop branch #49 fix: ignore path that might seem a broken link #49 fix: open api ref in a new tab #48
aws-powertools · Jun 1, 2020 · cd57c0f · cd57c0f
2 parents ce304ed + c3adb74
commit cd57c0f
Show file tree

Hide file tree

Showing 7 changed files with 560 additions and 64 deletions.
diff --git a/.github/workflows/python_docs.yml b/.github/workflows/python_docs.yml
@@ -7,6 +7,7 @@ on:
   push:
     branches:
       - master
+      - develop
 
 jobs:
   docs:
@@ -17,10 +18,28 @@ jobs:
         uses: actions/setup-python@v1
         with:
           python-version: "3.8"
+      - name: Capture branch and tag
+        id: branch_name
+        run: |
+          echo ::set-env name=SOURCE_BRANCH::${GITHUB_REF#refs/heads/}
+          echo ::set-env name=SOURCE_TAG::${GITHUB_REF#refs/tags/}
       - name: Build docs website
-        run: make build-docs
-      - name: Deploy docs
+        run: make build-docs-website
+      - name: Build docs API reference
+        if: env.SOURCE_BRANCH == 'master'
+        run: make build-docs-api
+      - name: Deploy docs website
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./dist
+          # when deploying docs website only
+          # we need to keep existing API docs checked in
+          # but only for dev branch
+          keep_files: true
+      - name: Deploy all docs
+        uses: peaceiris/actions-gh-pages@v3
+        if: env.SOURCE_BRANCH == 'master'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,38 +1,34 @@
-# HISTORY 
+# Changelog 
+All notable changes to this project will be documented in this file.
 
-## May 29th
+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).
 
-**0.9.4**
+## [Unreleased]
 
-* **Metrics**: Bugfix - Metrics were not correctly flushed, and cleared on every invocation
+## [0.9.4] - 2020-05-29
+### Fixed
+- **Metrics**: Fix issue where metrics were not correctly flushed, and cleared on every invocation
 
-## May 16th
+## [0.9.3] - 2020-05-16
+### Fixed
+- **Tracer**: Fix Runtime Error for nested sync due to incorrect loop usage
 
-**0.9.3**
+## [0.9.2] - 2020-05-14
+### Fixed
+- **Tracer**: Import aiohttp lazily so it's not a hard dependency
 
-* **Tracer**: Bugfix - Runtime Error for nested sync due to incorrect loop usage
-
-## May 14th
-
-**0.9.2**
-
-* **Tracer**: Bugfix - aiohttp lazy import so it's not a hard dependency
-
-## May 12th
-
-**0.9.0**
-
-* **Tracer**: Support for async functions in `Tracer` via `capture_method` decorator
-* **Tracer**: Support for `aiohttp` via `aiohttp_trace_config` trace config
-* **Tracer**: Support for patching specific modules via `patch_modules` param
-* **Tracer**: Document escape hatch mechanisms via `tracer.provider`
-
-## May 1st
-
-**0.8.1**
+## [0.9.0] - 2020-05-12
+### Added
+- **Tracer**: Support for async functions in `Tracer` via `capture_method` decorator
+- **Tracer**: Support for `aiohttp` via `aiohttp_trace_config` trace config
+- **Tracer**: Support for patching specific modules via `patch_modules` param
+- **Tracer**: Document escape hatch mechanisms via `tracer.provider`
 
+## [0.8.1] - 2020-05-1
+### Fixed
 * **Metrics**: Fix metric unit casting logic if one passes plain string (value or key)
-* **Metrics: **Fix `MetricUnit` enum values for
+* **Metrics:**: Fix `MetricUnit` enum values for
     - `BytesPerSecond`
     - `KilobytesPerSecond`
     - `MegabytesPerSecond`
@@ -45,40 +41,36 @@
     - `TerabitsPerSecond`
     - `CountPerSecond`
 
-## April 24th
-
-**0.8.0**
-
-* **Logger**: Introduces `Logger` class for stuctured logging as a replacement for `logger_setup`
-* **Logger**: Introduces `Logger.inject_lambda_context` decorator as a replacement for `logger_inject_lambda_context`
-* **Logger**: Raise `DeprecationWarning` exception for both `logger_setup`, `logger_inject_lambda_context`
-
-## April 20th, 2020
-
-**0.7.0**
-
-* **Middleware factory**: Introduces Middleware Factory to build your own middleware via `lambda_handler_decorator`
-* **Metrics**: Fixes metrics dimensions not being included correctly in EMF
-
-## April 9th, 2020
-
-**0.6.3**
-
-* **Logger**: Fix `log_metrics` decorator logic not calling the decorated function, and exception handling
+## [0.8.0] - 2020-04-24
+### Added
+- **Logger**: Introduced `Logger` class for stuctured logging as a replacement for `logger_setup`
+- **Logger**: Introduced `Logger.inject_lambda_context` decorator as a replacement for `logger_inject_lambda_context`
 
-## April 8th, 2020
+### Removed
+- **Logger**: Raise `DeprecationWarning` exception for both `logger_setup`, `logger_inject_lambda_context`
 
-**0.6.1**
+## [0.7.0] - 2020-04-20
+### Added
+- **Middleware factory**: Introduced Middleware Factory to build your own middleware via `lambda_handler_decorator`
 
-* **Metrics**: Introduces Metrics middleware to utilise CloudWatch Embedded Metric Format
-* **Metrics**: Adds deprecation warning for `log_metrics`
+### Fixed
+- **Metrics**: Fixed metrics dimensions not being included correctly in EMF
 
-## February 20th, 2020
+## [0.6.3] - 2020-04-09
+### Fixed
+- **Logger**: Fix `log_metrics` decorator logic not calling the decorated function, and exception handling
 
-**0.5.0**
+## [0.6.1] - 2020-04-08
+### Added
+- **Metrics**: Introduces Metrics middleware to utilise CloudWatch Embedded Metric Format
 
-* **Logger**: Introduces log sampling for debug - Thanks to [Danilo's contribution](https://github.com/awslabs/aws-lambda-powertools/pull/7)
+### Deprecated
+- **Metrics**: Added deprecation warning for `log_metrics`
 
-## November 15th, 2019 
+## [0.5.0] - 2020-02-20
+### Added
+- **Logger**: Introduced log sampling for debug - Thanks to [Danilo's contribution](https://github.com/awslabs/aws-lambda-powertools/pull/7)
 
-* Public beta release
+## [0.1.0] - 2019-11-15
+### Added
+- Public beta release
diff --git a/Makefile b/Makefile
@@ -29,16 +29,17 @@ build: pr
 	poetry run build
 
 build-docs:
-	mkdir -p dist/api
 	@$(MAKE) build-docs-website
 	@$(MAKE) build-docs-api
 
 build-docs-api: dev
+	mkdir -p dist/api
 	poetry run pdoc --html --output-dir dist/api/ ./aws_lambda_powertools --force
-	mv dist/api/aws_lambda_powertools/* dist/api/
+	mv -f dist/api/aws_lambda_powertools/* dist/api/
 	rm -rf dist/api/aws_lambda_powertools
 
 build-docs-website: dev-docs
+	mkdir -p dist
 	cd docs && npm run build
 	cp -R docs/public/* dist/
 

diff --git a/docs/content/core/logger.mdx b/docs/content/core/logger.mdx
@@ -187,8 +187,10 @@ def handler(event, context)
 
 You can dynamically set a percentage of your logs to **DEBUG** level using `sample_rate` param or via env var `POWERTOOLS_LOGGER_SAMPLE_RATE`.
 
-<Note type="warning">
-  This is possible due to <a href="https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html">AWS Lambda reuse of execution context</a>, <strong>however, it is not always guaranteed.</strong>
+This happens on an entire request basis, and <strong>DEBUG</strong> level is set at the constructor. That means, concurrent requests or infrequent invocations are more likely to occur as [new Lambda execution contexts are created](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-context.html), not reused.
+
+<Note type="info">
+  If you want this logic to happen on every invocation regardless whether Lambda reuses the execution environment or not, then create your Logger inside your Lambda handler.
 </Note><br/>
 
 ```python:title=collect.py

diff --git a/docs/gatsby-config.js b/docs/gatsby-config.js
@@ -53,7 +53,8 @@ module.exports = {
                 },
                 footerNavConfig: {
                     'API Reference': {
-                        href: 'https://awslabs.github.io/aws-lambda-powertools-python/api/'
+                        href: 'https://awslabs.github.io/aws-lambda-powertools-python/api/',
+                        target: '_blank'
                     },
                     Serverless: {
                         href: 'https://aws.amazon.com/serverless/'
@@ -67,7 +68,7 @@ module.exports = {
         {
             resolve: `gatsby-plugin-catch-links`,
             options: {
-                excludePattern: /(excluded-link|external)/,
+                excludePattern: /\/aws-lambda-powertools-python/,
             },
         },
         'gatsby-plugin-antd',