diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 3df8b4e968e..fdce088db17 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -21,16 +21,19 @@ name: Publish to PyPi # 7. Kick off Lambda Layer pipeline to publish latest version with extra dependencies as a SAR App # 8. Builds a fresh version of docs including Changelog updates # 9. Push latest release source code to master using release title as the commit message +# 10. Builds latest documentation for new release, and update latest alias pointing to the new release tag on: release: types: [published] jobs: - upload: + release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 + with: + fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v1 with: @@ -68,8 +71,21 @@ jobs: AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_DEFAULT_REGION: eu-west-1 AWS_DEFAULT_OUTPUT: json - - + - name: Setup doc deploy + run: | + git config --global user.name Docs deploy + git config --global user.email docs@dummy.bot.com + - name: Build docs website and API reference + run: | + make release-docs VERSION=${RELEASE_TAG_VERSION} ALIAS="latest" + poetry run mike set-default --push latest + - name: Deploy all docs + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./api + keep_files: true + destination_dir: ${{ env.RELEASE_TAG_VERSION }}/api sync_master: needs: upload diff --git a/.github/workflows/python_docs.yml b/.github/workflows/python_docs.yml index 5a721b00414..dcdd409b835 100644 --- a/.github/workflows/python_docs.yml +++ b/.github/workflows/python_docs.yml @@ -1,59 +1,41 @@ name: Docs on: - pull_request: - branches: - - master push: branches: - - master - - docs/mkdocs - # Disabled until docs support versioning per branch/release - # - develop - release: - types: [published] # update Docs upon new release + - develop jobs: - api-docs: + docs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v2 + with: + fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v1 with: python-version: "3.8" - - uses: actions/setup-node@v1 - with: - node-version: '12' - - name: Capture branch and tag - id: branch_name + - name: Install dependencies + run: make dev + - name: Setup doc deploy run: | - echo "SOURCE_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV - echo "SOURCE_TAG=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV - - name: Build docs website - run: make build-docs-website - - name: Build docs API reference - # if: env.SOURCE_BRANCH == 'master' # Disabled until docs support versioning per branch/release - run: make build-docs-api + git config --global user.name Docs deploy + git config --global user.email docs@dummy.bot.com + - name: Build docs website and API reference + run: make release-docs VERSION="develop" ALIAS="stage" - name: Deploy all docs uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./dist - - # Disabled until docs support versioning per branch/release - # - 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 + publish_dir: ./api + keep_files: true + destination_dir: develop/api + - name: Create redirect from old docs + run: | + git checkout gh-pages + test -f 404.html && echo "Redirect already set" && exit 0 + git checkout develop -- 404.html + git add 404.html + git commit -m "chore: set docs redirect" --no-verify + git push origin gh-pages -f diff --git a/.gitignore b/.gitignore index 9b1b99a95e4..ace70c8192d 100644 --- a/.gitignore +++ b/.gitignore @@ -300,3 +300,6 @@ wheelhouse docs/.cache/ docs/public node_modules +api/ +site/ +!404.html diff --git a/404.html b/404.html new file mode 100644 index 00000000000..2ee34f1988f --- /dev/null +++ b/404.html @@ -0,0 +1,20 @@ + + + + + + + + + + + diff --git a/Makefile b/Makefile index 429543b108d..f7b477ae49e 100644 --- a/Makefile +++ b/Makefile @@ -31,20 +31,18 @@ pr: lint pre-commit test security-baseline complexity-baseline build: pr poetry build -build-docs: - @$(MAKE) build-docs-website +release-docs: + @echo "Rebuilding docs" + rm -rf site api + @echo "Updating website docs" + poetry run mike deploy --push --update-aliases ${VERSION} ${ALIAS} + @echo "Building API docs" @$(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 -f dist/api/aws_lambda_powertools/* dist/api/ - rm -rf dist/api/aws_lambda_powertools - -build-docs-website: dev - mkdir -p dist - poetry run mkdocs build - cp -R site/* dist/ +build-docs-api: + poetry run pdoc --html --output-dir ./api/ ./aws_lambda_powertools --force + mv -f ./api/aws_lambda_powertools/* ./api/ + rm -rf ./api/aws_lambda_powertools docs-local: poetry run mkdocs serve diff --git a/mkdocs.yml b/mkdocs.yml index 0aa95693354..d1068f46f5c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,10 +1,13 @@ site_name: Lambda Powertools Python site_description: AWS Lambda Powertools for Python site_author: Amazon Web Services +repo_url: https://github.com/awslabs/aws-lambda-powertools-python +edit_uri: edit/develop/docs + nav: - Homepage: index.md - Changelog: changelog.md - - API reference: https://awslabs.github.io/aws-lambda-powertools-python/api/" target="_blank + - API reference: api/" target="_blank - Core utilities: - core/tracer.md - core/logger.md @@ -62,6 +65,6 @@ extra_javascript: - javascript/aws-amplify.min.js - javascript/extra.js - -repo_url: https://github.com/awslabs/aws-lambda-powertools-python -edit_uri: edit/develop/docs +extras: + version: + provider: mike diff --git a/poetry.lock b/poetry.lock index bfd989232a5..4d6b0d888d2 100644 --- a/poetry.lock +++ b/poetry.lock @@ -520,6 +520,24 @@ category = "dev" optional = false python-versions = "*" +[[package]] +name = "mike" +version = "0.6.0" +description = "Manage multiple versions of your MkDocs-powered documentation" +category = "dev" +optional = false +python-versions = "*" + +[package.dependencies] +jinja2 = "*" +mkdocs = ">=1.0" +packaging = "*" +"ruamel.yaml" = "*" + +[package.extras] +dev = ["coverage", "flake8 (>=3.0)", "pypandoc (>=1.4)"] +test = ["coverage", "flake8 (>=3.0)"] + [[package]] name = "mkdocs" version = "1.1.2" @@ -847,6 +865,29 @@ python-versions = "*" security = ["cryptography (>=1.3.4)", "idna (>=2.0.0)", "pyOpenSSL (>=0.14)"] socks = ["PySocks (>=1.5.6,!=1.5.7)", "win-inet-pton"] +[[package]] +name = "ruamel.yaml" +version = "0.16.13" +description = "ruamel.yaml is a YAML parser/emitter that supports roundtrip preservation of comments, seq/map flow style, and map key order" +category = "dev" +optional = false +python-versions = "*" + +[package.dependencies] +"ruamel.yaml.clib" = {version = ">=0.1.2", markers = "platform_python_implementation == \"CPython\" and python_version < \"3.10\""} + +[package.extras] +docs = ["ryd"] +jinja2 = ["ruamel.yaml.jinja2 (>=0.2)"] + +[[package]] +name = "ruamel.yaml.clib" +version = "0.2.2" +description = "C version of reader, parser and emitter for ruamel.yaml derived from libyaml" +category = "dev" +optional = false +python-versions = "*" + [[package]] name = "s3transfer" version = "0.3.6" @@ -1269,6 +1310,10 @@ mccabe = [ {file = "mccabe-0.6.1-py2.py3-none-any.whl", hash = "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42"}, {file = "mccabe-0.6.1.tar.gz", hash = "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"}, ] +mike = [ + {file = "mike-0.6.0-py3-none-any.whl", hash = "sha256:cef9b9c803ff5c3fbb410f51f5ceb00902a9fe16d9fabd93b69c65cf481ab5a1"}, + {file = "mike-0.6.0.tar.gz", hash = "sha256:6d6239de2a60d733da2f34617e9b9a14c4b5437423b47e524f14dc96d6ce5f2f"}, +] mkdocs = [ {file = "mkdocs-1.1.2-py3-none-any.whl", hash = "sha256:096f52ff52c02c7e90332d2e53da862fde5c062086e1b5356a6e392d5d60f5e9"}, {file = "mkdocs-1.1.2.tar.gz", hash = "sha256:f0b61e5402b99d7789efa032c7a74c90a20220a9c81749da06dbfbcbd52ffb39"}, @@ -1461,6 +1506,43 @@ requests = [ {file = "requests-2.15.1-py2.py3-none-any.whl", hash = "sha256:ff753b2196cd18b1bbeddc9dcd5c864056599f7a7d9a4fb5677e723efa2b7fb9"}, {file = "requests-2.15.1.tar.gz", hash = "sha256:e5659b9315a0610505e050bb7190bf6fa2ccee1ac295f2b760ef9d8a03ebbb2e"}, ] +"ruamel.yaml" = [ + {file = "ruamel.yaml-0.16.13-py2.py3-none-any.whl", hash = "sha256:64b06e7873eb8e1125525ecef7345447d786368cadca92a7cd9b59eae62e95a3"}, + {file = "ruamel.yaml-0.16.13.tar.gz", hash = "sha256:bb48c514222702878759a05af96f4b7ecdba9b33cd4efcf25c86b882cef3a942"}, +] +"ruamel.yaml.clib" = [ + {file = "ruamel.yaml.clib-0.2.2-cp27-cp27m-macosx_10_9_x86_64.whl", hash = "sha256:28116f204103cb3a108dfd37668f20abe6e3cafd0d3fd40dba126c732457b3cc"}, + {file = "ruamel.yaml.clib-0.2.2-cp27-cp27m-manylinux1_x86_64.whl", hash = "sha256:daf21aa33ee9b351f66deed30a3d450ab55c14242cfdfcd377798e2c0d25c9f1"}, + {file = "ruamel.yaml.clib-0.2.2-cp27-cp27m-win32.whl", hash = "sha256:30dca9bbcbb1cc858717438218d11eafb78666759e5094dd767468c0d577a7e7"}, + {file = "ruamel.yaml.clib-0.2.2-cp27-cp27m-win_amd64.whl", hash = "sha256:f6061a31880c1ed6b6ce341215336e2f3d0c1deccd84957b6fa8ca474b41e89f"}, + {file = "ruamel.yaml.clib-0.2.2-cp27-cp27mu-manylinux1_x86_64.whl", hash = "sha256:73b3d43e04cc4b228fa6fa5d796409ece6fcb53a6c270eb2048109cbcbc3b9c2"}, + {file = "ruamel.yaml.clib-0.2.2-cp35-cp35m-macosx_10_6_intel.whl", hash = "sha256:53b9dd1abd70e257a6e32f934ebc482dac5edb8c93e23deb663eac724c30b026"}, + {file = "ruamel.yaml.clib-0.2.2-cp35-cp35m-manylinux1_x86_64.whl", hash = "sha256:839dd72545ef7ba78fd2aa1a5dd07b33696adf3e68fae7f31327161c1093001b"}, + {file = "ruamel.yaml.clib-0.2.2-cp35-cp35m-manylinux2014_aarch64.whl", hash = "sha256:1236df55e0f73cd138c0eca074ee086136c3f16a97c2ac719032c050f7e0622f"}, + {file = "ruamel.yaml.clib-0.2.2-cp35-cp35m-win32.whl", hash = "sha256:b1e981fe1aff1fd11627f531524826a4dcc1f26c726235a52fcb62ded27d150f"}, + {file = "ruamel.yaml.clib-0.2.2-cp35-cp35m-win_amd64.whl", hash = "sha256:4e52c96ca66de04be42ea2278012a2342d89f5e82b4512fb6fb7134e377e2e62"}, + {file = "ruamel.yaml.clib-0.2.2-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:a873e4d4954f865dcb60bdc4914af7eaae48fb56b60ed6daa1d6251c72f5337c"}, + {file = "ruamel.yaml.clib-0.2.2-cp36-cp36m-manylinux1_x86_64.whl", hash = "sha256:ab845f1f51f7eb750a78937be9f79baea4a42c7960f5a94dde34e69f3cce1988"}, + {file = "ruamel.yaml.clib-0.2.2-cp36-cp36m-manylinux2014_aarch64.whl", hash = "sha256:2fd336a5c6415c82e2deb40d08c222087febe0aebe520f4d21910629018ab0f3"}, + {file = "ruamel.yaml.clib-0.2.2-cp36-cp36m-win32.whl", hash = "sha256:e9f7d1d8c26a6a12c23421061f9022bb62704e38211fe375c645485f38df34a2"}, + {file = "ruamel.yaml.clib-0.2.2-cp36-cp36m-win_amd64.whl", hash = "sha256:2602e91bd5c1b874d6f93d3086f9830f3e907c543c7672cf293a97c3fabdcd91"}, + {file = "ruamel.yaml.clib-0.2.2-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:44c7b0498c39f27795224438f1a6be6c5352f82cb887bc33d962c3a3acc00df6"}, + {file = "ruamel.yaml.clib-0.2.2-cp37-cp37m-manylinux1_x86_64.whl", hash = "sha256:8e8fd0a22c9d92af3a34f91e8a2594eeb35cba90ab643c5e0e643567dc8be43e"}, + {file = "ruamel.yaml.clib-0.2.2-cp37-cp37m-manylinux2014_aarch64.whl", hash = "sha256:75f0ee6839532e52a3a53f80ce64925ed4aed697dd3fa890c4c918f3304bd4f4"}, + {file = "ruamel.yaml.clib-0.2.2-cp37-cp37m-win32.whl", hash = "sha256:464e66a04e740d754170be5e740657a3b3b6d2bcc567f0c3437879a6e6087ff6"}, + {file = "ruamel.yaml.clib-0.2.2-cp37-cp37m-win_amd64.whl", hash = "sha256:52ae5739e4b5d6317b52f5b040b1b6639e8af68a5b8fd606a8b08658fbd0cab5"}, + {file = "ruamel.yaml.clib-0.2.2-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:4df5019e7783d14b79217ad9c56edf1ba7485d614ad5a385d1b3c768635c81c0"}, + {file = "ruamel.yaml.clib-0.2.2-cp38-cp38-manylinux1_x86_64.whl", hash = "sha256:5254af7d8bdf4d5484c089f929cb7f5bafa59b4f01d4f48adda4be41e6d29f99"}, + {file = "ruamel.yaml.clib-0.2.2-cp38-cp38-manylinux2014_aarch64.whl", hash = "sha256:8be05be57dc5c7b4a0b24edcaa2f7275866d9c907725226cdde46da09367d923"}, + {file = "ruamel.yaml.clib-0.2.2-cp38-cp38-win32.whl", hash = "sha256:74161d827407f4db9072011adcfb825b5258a5ccb3d2cd518dd6c9edea9e30f1"}, + {file = "ruamel.yaml.clib-0.2.2-cp38-cp38-win_amd64.whl", hash = "sha256:058a1cc3df2a8aecc12f983a48bda99315cebf55a3b3a5463e37bb599b05727b"}, + {file = "ruamel.yaml.clib-0.2.2-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:c6ac7e45367b1317e56f1461719c853fd6825226f45b835df7436bb04031fd8a"}, + {file = "ruamel.yaml.clib-0.2.2-cp39-cp39-manylinux1_x86_64.whl", hash = "sha256:b4b0d31f2052b3f9f9b5327024dc629a253a83d8649d4734ca7f35b60ec3e9e5"}, + {file = "ruamel.yaml.clib-0.2.2-cp39-cp39-manylinux2014_aarch64.whl", hash = "sha256:1f8c0a4577c0e6c99d208de5c4d3fd8aceed9574bb154d7a2b21c16bb924154c"}, + {file = "ruamel.yaml.clib-0.2.2-cp39-cp39-win32.whl", hash = "sha256:46d6d20815064e8bb023ea8628cfb7402c0f0e83de2c2227a88097e239a7dffd"}, + {file = "ruamel.yaml.clib-0.2.2-cp39-cp39-win_amd64.whl", hash = "sha256:6c0a5dc52fc74eb87c67374a4e554d4761fd42a4d01390b7e868b30d21f4b8bb"}, + {file = "ruamel.yaml.clib-0.2.2.tar.gz", hash = "sha256:2d24bd98af676f4990c4d715bcdc2a60b19c56a3fb3a763164d2d8ca0e806ba7"}, +] s3transfer = [ {file = "s3transfer-0.3.6-py2.py3-none-any.whl", hash = "sha256:5d48b1fd2232141a9d5fb279709117aaba506cacea7f86f11bc392f06bfa8fc2"}, {file = "s3transfer-0.3.6.tar.gz", hash = "sha256:c5dadf598762899d8cfaecf68eba649cd25b0ce93b6c954b156aaa3eed160547"}, diff --git a/pyproject.toml b/pyproject.toml index 77c446a56ae..c85f05e1a62 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,6 +52,7 @@ flake8-eradicate = "^1.0.0" flake8-bugbear = "^21.3.2" mkdocs-material = "^7.0.6" mkdocs-git-revision-date-plugin = "^0.3.1" +mike = "^0.6.0" [tool.poetry.extras]