From 1b86ed3f3bf7397c0556c06d0ba57b0ab0c7c87e Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 16:40:49 -0700 Subject: [PATCH 01/35] Remove superfluous comments from MkDocs config file These comments add nothing of value to the file. --- mkdocs.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index af4e07c09..460bcca96 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,17 +1,13 @@ -# Project information site_name: Arduino Lint site_description: Tool to check for problems with Arduino projects site_url: https://arduino.github.io/arduino-lint/ -# Repository repo_name: arduino/arduino-lint repo_url: https://github.com/arduino/arduino-lint edit_uri: "" -# Copyright copyright: Copyright 2020 ARDUINO SA (http://www.arduino.cc/) -# Theme theme: name: material logo: img/icon_mac_light.png @@ -19,7 +15,6 @@ theme: primary: teal accent: orange -# Extensions markdown_extensions: - markdown.extensions.codehilite: guess_lang: false @@ -43,7 +38,6 @@ markdown_extensions: nested_indent: 2 truly_sane: true -# Navigation nav: - Documentation Home: index.md - installation.md From f2ce3ae73834cffc12f557f77f8f4c1414edbf92 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 16:43:24 -0700 Subject: [PATCH 02/35] Add reference comment to MkDocs configuration file This will provide contributors with ready access to information about the purpose and usage of the file. --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 460bcca96..053eef5d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,4 @@ +# See: https://www.mkdocs.org/user-guide/configuration/ site_name: Arduino Lint site_description: Tool to check for problems with Arduino projects site_url: https://arduino.github.io/arduino-lint/ From 83b695bc9abf5c573683d7ff1ce3e32498b54f43 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 16:45:47 -0700 Subject: [PATCH 03/35] Add edit links to website pages This will encourage readers to submit pull requests for any corrections or improvements to the website content that might occur to them while using it. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 053eef5d6..2cd0d712e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,7 +5,7 @@ site_url: https://arduino.github.io/arduino-lint/ repo_name: arduino/arduino-lint repo_url: https://github.com/arduino/arduino-lint -edit_uri: "" +edit_uri: blob/main/docs/ copyright: Copyright 2020 ARDUINO SA (http://www.arduino.cc/) From 3e8db8bd7bf5fe05b52b393b8a0b66f9e46b9b93 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 16:50:06 -0700 Subject: [PATCH 04/35] Alphabeticize extensions list in MkDocs configuration file No functional effect, but can make it a little easier for the contributor to find the item of interest. --- mkdocs.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 2cd0d712e..634e8b74b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,23 +21,23 @@ markdown_extensions: guess_lang: false - markdown.extensions.toc: permalink: true + - mdx_truly_sane_lists: + nested_indent: 2 + truly_sane: true - pymdownx.betterem: smart_enable: all - pymdownx.details - pymdownx.emoji: - emoji_index: !!python/name:pymdownx.emoji.twemoji emoji_generator: !!python/name:pymdownx.emoji.to_svg + emoji_index: !!python/name:pymdownx.emoji.twemoji - pymdownx.magiclink: + repo: arduino-lint repo_url_shorthand: true user: arduino - repo: arduino-lint - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true - pymdownx.tilde - - mdx_truly_sane_lists: - nested_indent: 2 - truly_sane: true nav: - Documentation Home: index.md From 4759586f3ebae79496d76ee8f5018e3691843509 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 16:56:31 -0700 Subject: [PATCH 05/35] Use standardized page title for website home page The previous "Documentation Home" was unnecessarily verbose. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 634e8b74b..05b79821d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,7 +40,7 @@ markdown_extensions: - pymdownx.tilde nav: - - Documentation Home: index.md + - Home: index.md - installation.md - Command reference: commands/arduino-lint.md - CONTRIBUTING.md From b7df07242883a41004b49cec77bdef381d1aa46d Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 17:11:52 -0700 Subject: [PATCH 06/35] Update Python version used for project development to 3.9 --- .github/workflows/check-python-task.yml | 2 +- .github/workflows/publish-docs.yml | 2 +- .github/workflows/spell-check.yml | 2 +- .github/workflows/test.yml | 2 +- .github/workflows/validate-docs.yml | 2 +- docs/CONTRIBUTING.md | 2 +- poetry.lock | 48 ++----------------------- pyproject.toml | 2 +- 8 files changed, 9 insertions(+), 53 deletions(-) diff --git a/.github/workflows/check-python-task.yml b/.github/workflows/check-python-task.yml index 4d44cba55..32098a800 100644 --- a/.github/workflows/check-python-task.yml +++ b/.github/workflows/check-python-task.yml @@ -2,7 +2,7 @@ name: Check Python env: # See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python - PYTHON_VERSION: "3.8" + PYTHON_VERSION: "3.9" # See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows on: diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 28c658566..bc3273f24 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -55,7 +55,7 @@ jobs: - name: Install Python uses: actions/setup-python@v2 with: - python-version: "3.8" + python-version: "3.9" - name: Cache dependencies uses: actions/cache@v2 diff --git a/.github/workflows/spell-check.yml b/.github/workflows/spell-check.yml index 638da1941..f4d484330 100644 --- a/.github/workflows/spell-check.yml +++ b/.github/workflows/spell-check.yml @@ -18,7 +18,7 @@ jobs: - name: Install Python uses: actions/setup-python@v2 with: - python-version: "3.8" + python-version: "3.9" - name: Install Poetry run: pip install poetry diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c32772a7d..552cc2fdd 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -75,7 +75,7 @@ jobs: - name: Install Python uses: actions/setup-python@v2 with: - python-version: "3.8" + python-version: "3.9" - name: Install Poetry run: pip install poetry diff --git a/.github/workflows/validate-docs.yml b/.github/workflows/validate-docs.yml index 240677ac3..5cd2a9b3c 100644 --- a/.github/workflows/validate-docs.yml +++ b/.github/workflows/validate-docs.yml @@ -41,7 +41,7 @@ jobs: - name: Install Python uses: actions/setup-python@v2 with: - python-version: "3.8" + python-version: "3.9" - name: Cache dependencies uses: actions/cache@v2 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6bc4bfb64..bea7ee92c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -81,7 +81,7 @@ To build Arduino Lint from sources you need the following tools to be available If you want to run integration tests or work on documentation, you will also need: -- A working [Python](https://www.python.org/downloads/) environment, version 3.8 or later. +- A working [Python](https://www.python.org/downloads/) environment, version 3.9 or later. - [Poetry](https://python-poetry.org/docs/). ### Building the source code diff --git a/poetry.lock b/poetry.lock index 92b7e2e9a..566aa3c9d 100644 --- a/poetry.lock +++ b/poetry.lock @@ -465,21 +465,10 @@ category = "main" optional = false python-versions = "*" -[package.dependencies] -"ruamel.yaml.clib" = {version = ">=0.1.2", markers = "platform_python_implementation == \"CPython\" and python_version < \"3.9\""} - [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 = "main" -optional = false -python-versions = "*" - [[package]] name = "semver" version = "2.13.0" @@ -541,8 +530,8 @@ dev = ["py-make (>=0.1.0)", "twine", "argopt", "pydoc-markdown", "wheel"] [metadata] lock-version = "1.1" -python-versions = "^3.8" -content-hash = "5a6c43410cc27e2806a331ff4520af2ae89de3e72ba998ab6b7c17d1f36a6abd" +python-versions = "^3.9" +content-hash = "8936a33a911c00e7b0568138cc5c590df2983d7e94c79a0963d3b69af34c50fc" [metadata.files] appdirs = [ @@ -792,39 +781,6 @@ regex = [ {file = "ruamel.yaml-0.16.12-py2.py3-none-any.whl", hash = "sha256:012b9470a0ea06e4e44e99e7920277edf6b46eee0232a04487ea73a7386340a5"}, {file = "ruamel.yaml-0.16.12.tar.gz", hash = "sha256:076cc0bc34f1966d920a49f18b52b6ad559fbe656a0748e3535cf7b3f29ebf9e"}, ] -"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"}, -] semver = [ {file = "semver-2.13.0-py2.py3-none-any.whl", hash = "sha256:ced8b23dceb22134307c1b8abfa523da14198793d9787ac838e70e29e77458d4"}, {file = "semver-2.13.0.tar.gz", hash = "sha256:fa0fe2722ee1c3f57eac478820c3a5ae2f624af8264cbdf9000c980ff7f75e3f"}, diff --git a/pyproject.toml b/pyproject.toml index 908f6e4f9..fe928ab7a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ description = "arduino-lint" authors = ["Arduino "] [tool.poetry.dependencies] -python = "^3.8" +python = "^3.9" # Integration tests dependencies. invoke = "1.4.1" From 4e4753a31063699d10bec75537fc0b94f310aed9 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 17:27:11 -0700 Subject: [PATCH 07/35] Update website generation dependencies NOTE: the outdated versions of mike and mkdocs-material, previously in use required an approach to creating the version selector menu the author describes as "hacky". That "hacky" approach no longer works with the modern version of mkdocs-material. Fortunately, this is not a problem since the material theme now has official support for versioning via mike: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ This avoids the need for us to maintain JavaScript and CSS files. This does result in a change in the website GUI. The version selector menu has moved from where it was previously in the navigation panel to the title bar. --- docs/css/version-select.css | 5 - docs/js/version-select.js | 51 ------- mkdocs.yml | 8 +- poetry.lock | 281 +++++++++++++++++------------------- pyproject.toml | 4 +- 5 files changed, 139 insertions(+), 210 deletions(-) delete mode 100644 docs/css/version-select.css delete mode 100644 docs/js/version-select.js diff --git a/docs/css/version-select.css b/docs/css/version-select.css deleted file mode 100644 index e5bd98b85..000000000 --- a/docs/css/version-select.css +++ /dev/null @@ -1,5 +0,0 @@ -@media only screen and (max-width: 76.1875em) { - #version-selector { - padding: 0.6rem 0.8rem; - } -} diff --git a/docs/js/version-select.js b/docs/js/version-select.js deleted file mode 100644 index 61d8307e0..000000000 --- a/docs/js/version-select.js +++ /dev/null @@ -1,51 +0,0 @@ -window.addEventListener("DOMContentLoaded", function () { - // This is a bit hacky. Figure out the base URL from a known CSS file the - // template refers to... - var ex = new RegExp("/?assets/fonts/material-icons.css$") - var sheet = document.querySelector('link[href$="material-icons.css"]') - - var REL_BASE_URL = sheet.getAttribute("href").replace(ex, "") - var ABS_BASE_URL = sheet.href.replace(ex, "") - var CURRENT_VERSION = ABS_BASE_URL.split("/").pop() - - function makeSelect(options, selected) { - var select = document.createElement("select") - select.classList.add("form-control") - - options.forEach(function (i) { - var option = new Option(i.text, i.value, undefined, i.value === selected) - select.add(option) - }) - - return select - } - - var xhr = new XMLHttpRequest() - xhr.open("GET", ABS_BASE_URL + "/../versions.json") - xhr.onload = function () { - var versions = JSON.parse(this.responseText) - - var realVersion = versions.find(function (i) { - return i.version === CURRENT_VERSION || i.aliases.includes(CURRENT_VERSION) - }).version - - var select = makeSelect( - versions.map(function (i) { - return { text: i.title, value: i.version } - }), - realVersion - ) - select.addEventListener("change", function (event) { - window.location.href = ABS_BASE_URL + "/../" + this.value - }) - - var container = document.createElement("div") - container.id = "version-selector" - container.className = "md-nav__item" - container.appendChild(select) - - var sidebar = document.querySelector(".md-nav--primary > .md-nav__list") - sidebar.parentNode.insertBefore(container, sidebar) - } - xhr.send() -}) diff --git a/mkdocs.yml b/mkdocs.yml index 05b79821d..96feaa79d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,8 +45,6 @@ nav: - Command reference: commands/arduino-lint.md - CONTRIBUTING.md -extra_css: - - css/version-select.css - -extra_javascript: - - js/version-select.js +extra: + version: + provider: mike diff --git a/poetry.lock b/poetry.lock index 566aa3c9d..39cec3e24 100644 --- a/poetry.lock +++ b/poetry.lock @@ -103,12 +103,18 @@ python-versions = "*" flake8 = "*" [[package]] -name = "future" -version = "0.18.2" -description = "Clean single-source support for Python 3 and 2" +name = "ghp-import" +version = "2.0.1" +description = "Copy your docs directly to the gh-pages branch." category = "main" optional = false -python-versions = ">=2.6, !=3.0.*, !=3.1.*, !=3.2.*" +python-versions = "*" + +[package.dependencies] +python-dateutil = ">=2.8.1" + +[package.extras] +dev = ["twine", "markdown", "flake8"] [[package]] name = "gitdb" @@ -132,6 +138,22 @@ python-versions = ">=3.4" [package.dependencies] gitdb = ">=4.0.1,<5" +[[package]] +name = "importlib-metadata" +version = "4.6.3" +description = "Read metadata from Python packages" +category = "main" +optional = false +python-versions = ">=3.6" + +[package.dependencies] +zipp = ">=0.5" + +[package.extras] +docs = ["sphinx", "jaraco.packaging (>=8.2)", "rst.linker (>=1.9)"] +perf = ["ipython"] +testing = ["pytest (>=4.6)", "pytest-checkdocs (>=2.4)", "pytest-flake8", "pytest-cov", "pytest-enabler (>=1.0.1)", "packaging", "pep517", "pyfakefs", "flufl.flake8", "pytest-perf (>=0.9.2)", "pytest-black (>=0.3.7)", "pytest-mypy", "importlib-resources (>=1.3)"] + [[package]] name = "iniconfig" version = "1.1.1" @@ -162,42 +184,6 @@ MarkupSafe = ">=0.23" [package.extras] i18n = ["Babel (>=0.8)"] -[[package]] -name = "joblib" -version = "1.0.0" -description = "Lightweight pipelining with Python functions" -category = "main" -optional = false -python-versions = ">=3.6" - -[[package]] -name = "livereload" -version = "2.6.3" -description = "Python LiveReload is an awesome tool for web developers" -category = "main" -optional = false -python-versions = "*" - -[package.dependencies] -six = "*" -tornado = {version = "*", markers = "python_version > \"2.7\""} - -[[package]] -name = "lunr" -version = "0.5.8" -description = "A Python implementation of Lunr.js" -category = "main" -optional = false -python-versions = "*" - -[package.dependencies] -future = ">=0.16.0" -nltk = {version = ">=3.2.5", optional = true, markers = "python_version > \"2.7\" and extra == \"languages\""} -six = ">=1.11.0" - -[package.extras] -languages = ["nltk (>=3.2.5,<3.5)", "nltk (>=3.2.5)"] - [[package]] name = "markdown" version = "3.3.3" @@ -236,6 +222,14 @@ python-versions = "*" [package.dependencies] Markdown = ">=2.6" +[[package]] +name = "mergedeep" +version = "1.3.4" +description = "A deep merge function for 🐍." +category = "main" +optional = false +python-versions = ">=3.6" + [[package]] name = "mike" version = "0.5.5" @@ -256,24 +250,30 @@ test = ["coverage", "flake8 (>=3.0)"] [[package]] name = "mkdocs" -version = "1.1.2" +version = "1.2.2" description = "Project documentation with Markdown." category = "main" optional = false -python-versions = ">=3.5" +python-versions = ">=3.6" [package.dependencies] click = ">=3.3" +ghp-import = ">=1.0" +importlib-metadata = ">=3.10" Jinja2 = ">=2.10.1" -livereload = ">=2.5.1" -lunr = {version = "0.5.8", extras = ["languages"]} Markdown = ">=3.2.1" +mergedeep = ">=1.3.4" +packaging = ">=20.5" PyYAML = ">=3.10" -tornado = ">=5.0" +pyyaml-env-tag = ">=0.1" +watchdog = ">=2.0" + +[package.extras] +i18n = ["babel (>=2.9.0)"] [[package]] name = "mkdocs-material" -version = "4.6.3" +version = "7.2.2" description = "A Material Design theme for MkDocs" category = "main" optional = false @@ -281,9 +281,21 @@ python-versions = "*" [package.dependencies] markdown = ">=3.2" -mkdocs = ">=1.0" +mkdocs = ">=1.1" +mkdocs-material-extensions = ">=1.0" Pygments = ">=2.4" -pymdown-extensions = ">=6.3" +pymdown-extensions = ">=7.0" + +[[package]] +name = "mkdocs-material-extensions" +version = "1.0.1" +description = "Extension pack for Python Markdown." +category = "main" +optional = false +python-versions = ">=3.5" + +[package.dependencies] +mkdocs-material = ">=5.0.0" [[package]] name = "mypy-extensions" @@ -293,28 +305,6 @@ category = "dev" optional = false python-versions = "*" -[[package]] -name = "nltk" -version = "3.5" -description = "Natural Language Toolkit" -category = "main" -optional = false -python-versions = "*" - -[package.dependencies] -click = "*" -joblib = "*" -regex = "*" -tqdm = "*" - -[package.extras] -all = ["requests", "numpy", "python-crfsuite", "scikit-learn", "twython", "pyparsing", "scipy", "matplotlib", "gensim"] -corenlp = ["requests"] -machine_learning = ["gensim", "numpy", "python-crfsuite", "scikit-learn", "scipy"] -plot = ["matplotlib"] -tgrep = ["pyparsing"] -twitter = ["twython"] - [[package]] name = "packaging" version = "20.8" @@ -449,11 +439,22 @@ category = "main" optional = false python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" +[[package]] +name = "pyyaml-env-tag" +version = "0.1" +description = "A custom YAML tag for referencing environment variables in YAML files. " +category = "main" +optional = false +python-versions = ">=3.6" + +[package.dependencies] +pyyaml = "*" + [[package]] name = "regex" version = "2020.11.13" description = "Alternative regular expression module, to replace re." -category = "main" +category = "dev" optional = false python-versions = "*" @@ -510,28 +511,32 @@ optional = false python-versions = ">=3.6" [[package]] -name = "tornado" -version = "6.1" -description = "Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed." +name = "watchdog" +version = "2.1.3" +description = "Filesystem events monitoring" category = "main" optional = false -python-versions = ">= 3.5" +python-versions = ">=3.6" + +[package.extras] +watchmedo = ["PyYAML (>=3.10)", "argh (>=0.24.1)"] [[package]] -name = "tqdm" -version = "4.54.1" -description = "Fast, Extensible Progress Meter" +name = "zipp" +version = "3.5.0" +description = "Backport of pathlib-compatible object wrapper for zip files" category = "main" optional = false -python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,>=2.7" +python-versions = ">=3.6" [package.extras] -dev = ["py-make (>=0.1.0)", "twine", "argopt", "pydoc-markdown", "wheel"] +docs = ["sphinx", "jaraco.packaging (>=8.2)", "rst.linker (>=1.9)"] +testing = ["pytest (>=4.6)", "pytest-checkdocs (>=2.4)", "pytest-flake8", "pytest-cov", "pytest-enabler (>=1.0.1)", "jaraco.itertools", "func-timeout", "pytest-black (>=0.3.7)", "pytest-mypy"] [metadata] lock-version = "1.1" python-versions = "^3.9" -content-hash = "8936a33a911c00e7b0568138cc5c590df2983d7e94c79a0963d3b69af34c50fc" +content-hash = "64ddf6ae94dabf07642e06bb8b54784702b1349abf5c7b398f6c35b4fb2d40e9" [metadata.files] appdirs = [ @@ -570,8 +575,8 @@ flake8-polyfill = [ {file = "flake8-polyfill-1.0.2.tar.gz", hash = "sha256:e44b087597f6da52ec6393a709e7108b2905317d0c0b744cdca6208e670d8eda"}, {file = "flake8_polyfill-1.0.2-py2.py3-none-any.whl", hash = "sha256:12be6a34ee3ab795b19ca73505e7b55826d5f6ad7230d31b18e106400169b9e9"}, ] -future = [ - {file = "future-0.18.2.tar.gz", hash = "sha256:b1bead90b70cf6ec3f0710ae53a525360fa360d306a86583adc6bf83a4db537d"}, +ghp-import = [ + {file = "ghp-import-2.0.1.tar.gz", hash = "sha256:753de2eace6e0f7d4edfb3cce5e3c3b98cd52aadb80163303d1d036bda7b4483"}, ] gitdb = [ {file = "gitdb-4.0.5-py3-none-any.whl", hash = "sha256:91f36bfb1ab7949b3b40e23736db18231bf7593edada2ba5c3a174a7b23657ac"}, @@ -581,6 +586,10 @@ gitpython = [ {file = "GitPython-3.1.11-py3-none-any.whl", hash = "sha256:6eea89b655917b500437e9668e4a12eabdcf00229a0df1762aabd692ef9b746b"}, {file = "GitPython-3.1.11.tar.gz", hash = "sha256:befa4d101f91bad1b632df4308ec64555db684c360bd7d2130b4807d49ce86b8"}, ] +importlib-metadata = [ + {file = "importlib_metadata-4.6.3-py3-none-any.whl", hash = "sha256:51c6635429c77cf1ae634c997ff9e53ca3438b495f10a55ba28594dd69764a8b"}, + {file = "importlib_metadata-4.6.3.tar.gz", hash = "sha256:0645585859e9a6689c523927a5032f2ba5919f1f7d0e84bd4533312320de1ff9"}, +] iniconfig = [ {file = "iniconfig-1.1.1-py2.py3-none-any.whl", hash = "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3"}, {file = "iniconfig-1.1.1.tar.gz", hash = "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"}, @@ -594,17 +603,6 @@ jinja2 = [ {file = "Jinja2-2.11.2-py2.py3-none-any.whl", hash = "sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035"}, {file = "Jinja2-2.11.2.tar.gz", hash = "sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0"}, ] -joblib = [ - {file = "joblib-1.0.0-py3-none-any.whl", hash = "sha256:75ead23f13484a2a414874779d69ade40d4fa1abe62b222a23cd50d4bc822f6f"}, - {file = "joblib-1.0.0.tar.gz", hash = "sha256:7ad866067ac1fdec27d51c8678ea760601b70e32ff1881d4dc8e1171f2b64b24"}, -] -livereload = [ - {file = "livereload-2.6.3.tar.gz", hash = "sha256:776f2f865e59fde56490a56bcc6773b6917366bce0c267c60ee8aaf1a0959869"}, -] -lunr = [ - {file = "lunr-0.5.8-py2.py3-none-any.whl", hash = "sha256:aab3f489c4d4fab4c1294a257a30fec397db56f0a50273218ccc3efdbf01d6ca"}, - {file = "lunr-0.5.8.tar.gz", hash = "sha256:c4fb063b98eff775dd638b3df380008ae85e6cb1d1a24d1cd81a10ef6391c26e"}, -] markdown = [ {file = "Markdown-3.3.3-py3-none-any.whl", hash = "sha256:c109c15b7dc20a9ac454c9e6025927d44460b85bd039da028d85e2b6d0bcc328"}, {file = "Markdown-3.3.3.tar.gz", hash = "sha256:5d9f2b5ca24bc4c7a390d22323ca4bad200368612b5aaa7796babf971d2b2f18"}, @@ -652,25 +650,30 @@ mdx-truly-sane-lists = [ {file = "mdx_truly_sane_lists-1.2-py3-none-any.whl", hash = "sha256:cc8bfa00f331403504e12377a9c94e6b40fc7db031e283316baeeeeac68f1da9"}, {file = "mdx_truly_sane_lists-1.2.tar.gz", hash = "sha256:4600ade0fbd452db8233e25d644b62f59b2798e40595ea2e1923e29bc40c5b98"}, ] +mergedeep = [ + {file = "mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307"}, + {file = "mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8"}, +] mike = [ {file = "mike-0.5.5-py3-none-any.whl", hash = "sha256:9e15a240f9aca36645789897fe53a8726e4d2b40ab8849f184dae87fe5a3f0cd"}, {file = "mike-0.5.5.tar.gz", hash = "sha256:0aab7a4f9e2394057ae6ce4e0732b2216a2d247e5b6c8aa2059720e9ea184648"}, ] mkdocs = [ - {file = "mkdocs-1.1.2-py3-none-any.whl", hash = "sha256:096f52ff52c02c7e90332d2e53da862fde5c062086e1b5356a6e392d5d60f5e9"}, - {file = "mkdocs-1.1.2.tar.gz", hash = "sha256:f0b61e5402b99d7789efa032c7a74c90a20220a9c81749da06dbfbcbd52ffb39"}, + {file = "mkdocs-1.2.2-py3-none-any.whl", hash = "sha256:d019ff8e17ec746afeb54eb9eb4112b5e959597aebc971da46a5c9486137f0ff"}, + {file = "mkdocs-1.2.2.tar.gz", hash = "sha256:a334f5bd98ec960638511366eb8c5abc9c99b9083a0ed2401d8791b112d6b078"}, ] mkdocs-material = [ - {file = "mkdocs-material-4.6.3.tar.gz", hash = "sha256:1d486635b03f5a2ec87325842f7b10c7ae7daa0eef76b185572eece6a6ea212c"}, - {file = "mkdocs_material-4.6.3-py2.py3-none-any.whl", hash = "sha256:7f3afa0a09c07d0b89a6a9755fdb00513aee8f0cec3538bb903325c80f66f444"}, + {file = "mkdocs-material-7.2.2.tar.gz", hash = "sha256:4f501e139e2f8546653e7d8777c9b97ca639d03d8c86345a60609864cc5bbb03"}, + {file = "mkdocs_material-7.2.2-py2.py3-none-any.whl", hash = "sha256:76de22213f0e0319b9bddf1bfa86530e93efb4a604e9ddf8f8419f0438572523"}, +] +mkdocs-material-extensions = [ + {file = "mkdocs-material-extensions-1.0.1.tar.gz", hash = "sha256:6947fb7f5e4291e3c61405bad3539d81e0b3cd62ae0d66ced018128af509c68f"}, + {file = "mkdocs_material_extensions-1.0.1-py3-none-any.whl", hash = "sha256:d90c807a88348aa6d1805657ec5c0b2d8d609c110e62b9dce4daf7fa981fa338"}, ] mypy-extensions = [ {file = "mypy_extensions-0.4.3-py2.py3-none-any.whl", hash = "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d"}, {file = "mypy_extensions-0.4.3.tar.gz", hash = "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8"}, ] -nltk = [ - {file = "nltk-3.5.zip", hash = "sha256:845365449cd8c5f9731f7cb9f8bd6fd0767553b9d53af9eb1b3abf7700936b35"}, -] packaging = [ {file = "packaging-20.8-py2.py3-none-any.whl", hash = "sha256:24e0da08660a87484d1602c30bb4902d74816b6985b93de36926f5bc95741858"}, {file = "packaging-20.8.tar.gz", hash = "sha256:78598185a7008a470d64526a8059de9aaa449238f280fc9eb6b13ba6c4109093"}, @@ -734,6 +737,10 @@ pyyaml = [ {file = "PyYAML-5.3.1-cp39-cp39-win_amd64.whl", hash = "sha256:6034f55dab5fea9e53f436aa68fa3ace2634918e8b5994d82f3621c04ff5ed2e"}, {file = "PyYAML-5.3.1.tar.gz", hash = "sha256:b8eac752c5e14d3eca0e6dd9199cd627518cb5ec06add0de9d32baeee6fe645d"}, ] +pyyaml-env-tag = [ + {file = "pyyaml_env_tag-0.1-py3-none-any.whl", hash = "sha256:af31106dec8a4d68c60207c1886031cbf839b68aa7abccdb19868200532c2069"}, + {file = "pyyaml_env_tag-0.1.tar.gz", hash = "sha256:70092675bda14fdec33b31ba77e7543de9ddc88f2e5b99160396572d11525bdb"}, +] regex = [ {file = "regex-2020.11.13-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:8b882a78c320478b12ff024e81dc7d43c1462aa4a3341c754ee65d857a521f85"}, {file = "regex-2020.11.13-cp36-cp36m-manylinux1_i686.whl", hash = "sha256:a63f1a07932c9686d2d416fb295ec2c01ab246e89b4d58e5fa468089cab44b70"}, @@ -801,50 +808,30 @@ tomli = [ {file = "tomli-1.2.0-py3-none-any.whl", hash = "sha256:056f0376bf5a6b182c513f9582c1e5b0487265eb6c48842b69aa9ca1cd5f640a"}, {file = "tomli-1.2.0.tar.gz", hash = "sha256:d60e681734099207a6add7a10326bc2ddd1fdc36c1b0f547d00ef73ac63739c2"}, ] -tornado = [ - {file = "tornado-6.1-cp35-cp35m-macosx_10_9_x86_64.whl", hash = "sha256:d371e811d6b156d82aa5f9a4e08b58debf97c302a35714f6f45e35139c332e32"}, - {file = "tornado-6.1-cp35-cp35m-manylinux1_i686.whl", hash = "sha256:0d321a39c36e5f2c4ff12b4ed58d41390460f798422c4504e09eb5678e09998c"}, - {file = "tornado-6.1-cp35-cp35m-manylinux1_x86_64.whl", hash = "sha256:9de9e5188a782be6b1ce866e8a51bc76a0fbaa0e16613823fc38e4fc2556ad05"}, - {file = "tornado-6.1-cp35-cp35m-manylinux2010_i686.whl", hash = "sha256:61b32d06ae8a036a6607805e6720ef00a3c98207038444ba7fd3d169cd998910"}, - {file = "tornado-6.1-cp35-cp35m-manylinux2010_x86_64.whl", hash = "sha256:3e63498f680547ed24d2c71e6497f24bca791aca2fe116dbc2bd0ac7f191691b"}, - {file = "tornado-6.1-cp35-cp35m-manylinux2014_aarch64.whl", hash = "sha256:6c77c9937962577a6a76917845d06af6ab9197702a42e1346d8ae2e76b5e3675"}, - {file = "tornado-6.1-cp35-cp35m-win32.whl", hash = "sha256:6286efab1ed6e74b7028327365cf7346b1d777d63ab30e21a0f4d5b275fc17d5"}, - {file = "tornado-6.1-cp35-cp35m-win_amd64.whl", hash = "sha256:fa2ba70284fa42c2a5ecb35e322e68823288a4251f9ba9cc77be04ae15eada68"}, - {file = "tornado-6.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:0a00ff4561e2929a2c37ce706cb8233b7907e0cdc22eab98888aca5dd3775feb"}, - {file = "tornado-6.1-cp36-cp36m-manylinux1_i686.whl", hash = "sha256:748290bf9112b581c525e6e6d3820621ff020ed95af6f17fedef416b27ed564c"}, - {file = "tornado-6.1-cp36-cp36m-manylinux1_x86_64.whl", hash = "sha256:e385b637ac3acaae8022e7e47dfa7b83d3620e432e3ecb9a3f7f58f150e50921"}, - {file = "tornado-6.1-cp36-cp36m-manylinux2010_i686.whl", hash = "sha256:25ad220258349a12ae87ede08a7b04aca51237721f63b1808d39bdb4b2164558"}, - {file = "tornado-6.1-cp36-cp36m-manylinux2010_x86_64.whl", hash = "sha256:65d98939f1a2e74b58839f8c4dab3b6b3c1ce84972ae712be02845e65391ac7c"}, - {file = "tornado-6.1-cp36-cp36m-manylinux2014_aarch64.whl", hash = "sha256:e519d64089b0876c7b467274468709dadf11e41d65f63bba207e04217f47c085"}, - {file = "tornado-6.1-cp36-cp36m-win32.whl", hash = "sha256:b87936fd2c317b6ee08a5741ea06b9d11a6074ef4cc42e031bc6403f82a32575"}, - {file = "tornado-6.1-cp36-cp36m-win_amd64.whl", hash = "sha256:cc0ee35043162abbf717b7df924597ade8e5395e7b66d18270116f8745ceb795"}, - {file = "tornado-6.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:7250a3fa399f08ec9cb3f7b1b987955d17e044f1ade821b32e5f435130250d7f"}, - {file = "tornado-6.1-cp37-cp37m-manylinux1_i686.whl", hash = "sha256:ed3ad863b1b40cd1d4bd21e7498329ccaece75db5a5bf58cd3c9f130843e7102"}, - {file = "tornado-6.1-cp37-cp37m-manylinux1_x86_64.whl", hash = "sha256:dcef026f608f678c118779cd6591c8af6e9b4155c44e0d1bc0c87c036fb8c8c4"}, - {file = "tornado-6.1-cp37-cp37m-manylinux2010_i686.whl", hash = "sha256:70dec29e8ac485dbf57481baee40781c63e381bebea080991893cd297742b8fd"}, - {file = "tornado-6.1-cp37-cp37m-manylinux2010_x86_64.whl", hash = "sha256:d3f7594930c423fd9f5d1a76bee85a2c36fd8b4b16921cae7e965f22575e9c01"}, - {file = "tornado-6.1-cp37-cp37m-manylinux2014_aarch64.whl", hash = "sha256:3447475585bae2e77ecb832fc0300c3695516a47d46cefa0528181a34c5b9d3d"}, - {file = "tornado-6.1-cp37-cp37m-win32.whl", hash = "sha256:e7229e60ac41a1202444497ddde70a48d33909e484f96eb0da9baf8dc68541df"}, - {file = "tornado-6.1-cp37-cp37m-win_amd64.whl", hash = "sha256:cb5ec8eead331e3bb4ce8066cf06d2dfef1bfb1b2a73082dfe8a161301b76e37"}, - {file = "tornado-6.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:20241b3cb4f425e971cb0a8e4ffc9b0a861530ae3c52f2b0434e6c1b57e9fd95"}, - {file = "tornado-6.1-cp38-cp38-manylinux1_i686.whl", hash = "sha256:c77da1263aa361938476f04c4b6c8916001b90b2c2fdd92d8d535e1af48fba5a"}, - {file = "tornado-6.1-cp38-cp38-manylinux1_x86_64.whl", hash = "sha256:fba85b6cd9c39be262fcd23865652920832b61583de2a2ca907dbd8e8a8c81e5"}, - {file = "tornado-6.1-cp38-cp38-manylinux2010_i686.whl", hash = "sha256:1e8225a1070cd8eec59a996c43229fe8f95689cb16e552d130b9793cb570a288"}, - {file = "tornado-6.1-cp38-cp38-manylinux2010_x86_64.whl", hash = "sha256:d14d30e7f46a0476efb0deb5b61343b1526f73ebb5ed84f23dc794bdb88f9d9f"}, - {file = "tornado-6.1-cp38-cp38-manylinux2014_aarch64.whl", hash = "sha256:8f959b26f2634a091bb42241c3ed8d3cedb506e7c27b8dd5c7b9f745318ddbb6"}, - {file = "tornado-6.1-cp38-cp38-win32.whl", hash = "sha256:34ca2dac9e4d7afb0bed4677512e36a52f09caa6fded70b4e3e1c89dbd92c326"}, - {file = "tornado-6.1-cp38-cp38-win_amd64.whl", hash = "sha256:6196a5c39286cc37c024cd78834fb9345e464525d8991c21e908cc046d1cc02c"}, - {file = "tornado-6.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:f0ba29bafd8e7e22920567ce0d232c26d4d47c8b5cf4ed7b562b5db39fa199c5"}, - {file = "tornado-6.1-cp39-cp39-manylinux1_i686.whl", hash = "sha256:33892118b165401f291070100d6d09359ca74addda679b60390b09f8ef325ffe"}, - {file = "tornado-6.1-cp39-cp39-manylinux1_x86_64.whl", hash = "sha256:7da13da6f985aab7f6f28debab00c67ff9cbacd588e8477034c0652ac141feea"}, - {file = "tornado-6.1-cp39-cp39-manylinux2010_i686.whl", hash = "sha256:e0791ac58d91ac58f694d8d2957884df8e4e2f6687cdf367ef7eb7497f79eaa2"}, - {file = "tornado-6.1-cp39-cp39-manylinux2010_x86_64.whl", hash = "sha256:66324e4e1beede9ac79e60f88de548da58b1f8ab4b2f1354d8375774f997e6c0"}, - {file = "tornado-6.1-cp39-cp39-manylinux2014_aarch64.whl", hash = "sha256:a48900ecea1cbb71b8c71c620dee15b62f85f7c14189bdeee54966fbd9a0c5bd"}, - {file = "tornado-6.1-cp39-cp39-win32.whl", hash = "sha256:d3d20ea5782ba63ed13bc2b8c291a053c8d807a8fa927d941bd718468f7b950c"}, - {file = "tornado-6.1-cp39-cp39-win_amd64.whl", hash = "sha256:548430be2740e327b3fe0201abe471f314741efcb0067ec4f2d7dcfb4825f3e4"}, - {file = "tornado-6.1.tar.gz", hash = "sha256:33c6e81d7bd55b468d2e793517c909b139960b6c790a60b7991b9b6b76fb9791"}, -] -tqdm = [ - {file = "tqdm-4.54.1-py2.py3-none-any.whl", hash = "sha256:d4f413aecb61c9779888c64ddf0c62910ad56dcbe857d8922bb505d4dbff0df1"}, - {file = "tqdm-4.54.1.tar.gz", hash = "sha256:38b658a3e4ecf9b4f6f8ff75ca16221ae3378b2e175d846b6b33ea3a20852cf5"}, +watchdog = [ + {file = "watchdog-2.1.3-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:9628f3f85375a17614a2ab5eac7665f7f7be8b6b0a2a228e6f6a2e91dd4bfe26"}, + {file = "watchdog-2.1.3-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:acc4e2d5be6f140f02ee8590e51c002829e2c33ee199036fcd61311d558d89f4"}, + {file = "watchdog-2.1.3-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:85b851237cf3533fabbc034ffcd84d0fa52014b3121454e5f8b86974b531560c"}, + {file = "watchdog-2.1.3-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:a12539ecf2478a94e4ba4d13476bb2c7a2e0a2080af2bb37df84d88b1b01358a"}, + {file = "watchdog-2.1.3-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:6fe9c8533e955c6589cfea6f3f0a1a95fb16867a211125236c82e1815932b5d7"}, + {file = "watchdog-2.1.3-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:d9456f0433845e7153b102fffeb767bde2406b76042f2216838af3b21707894e"}, + {file = "watchdog-2.1.3-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:fd8c595d5a93abd441ee7c5bb3ff0d7170e79031520d113d6f401d0cf49d7c8f"}, + {file = "watchdog-2.1.3-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:0bcfe904c7d404eb6905f7106c54873503b442e8e918cc226e1828f498bdc0ca"}, + {file = "watchdog-2.1.3-pp36-pypy36_pp73-macosx_10_9_x86_64.whl", hash = "sha256:bf84bd94cbaad8f6b9cbaeef43080920f4cb0e61ad90af7106b3de402f5fe127"}, + {file = "watchdog-2.1.3-pp37-pypy37_pp73-macosx_10_9_x86_64.whl", hash = "sha256:b8ddb2c9f92e0c686ea77341dcb58216fa5ff7d5f992c7278ee8a392a06e86bb"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_aarch64.whl", hash = "sha256:8805a5f468862daf1e4f4447b0ccf3acaff626eaa57fbb46d7960d1cf09f2e6d"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_armv7l.whl", hash = "sha256:3e305ea2757f81d8ebd8559d1a944ed83e3ab1bdf68bcf16ec851b97c08dc035"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_i686.whl", hash = "sha256:431a3ea70b20962e6dee65f0eeecd768cd3085ea613ccb9b53c8969de9f6ebd2"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_ppc64.whl", hash = "sha256:e4929ac2aaa2e4f1a30a36751160be391911da463a8799460340901517298b13"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:201cadf0b8c11922f54ec97482f95b2aafca429c4c3a4bb869a14f3c20c32686"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_s390x.whl", hash = "sha256:3a7d242a7963174684206093846537220ee37ba9986b824a326a8bb4ef329a33"}, + {file = "watchdog-2.1.3-py3-none-manylinux2014_x86_64.whl", hash = "sha256:54e057727dd18bd01a3060dbf5104eb5a495ca26316487e0f32a394fd5fe725a"}, + {file = "watchdog-2.1.3-py3-none-win32.whl", hash = "sha256:b5fc5c127bad6983eecf1ad117ab3418949f18af9c8758bd10158be3647298a9"}, + {file = "watchdog-2.1.3-py3-none-win_amd64.whl", hash = "sha256:44acad6f642996a2b50bb9ce4fb3730dde08f23e79e20cd3d8e2a2076b730381"}, + {file = "watchdog-2.1.3-py3-none-win_ia64.whl", hash = "sha256:0bcdf7b99b56a3ae069866c33d247c9994ffde91b620eaf0306b27e099bd1ae0"}, + {file = "watchdog-2.1.3.tar.gz", hash = "sha256:e5236a8e8602ab6db4b873664c2d356c365ab3cac96fbdec4970ad616415dd45"}, +] +zipp = [ + {file = "zipp-3.5.0-py3-none-any.whl", hash = "sha256:957cfda87797e389580cb8b9e3870841ca991e2125350677b2ca83a0e99390a3"}, + {file = "zipp-3.5.0.tar.gz", hash = "sha256:f5812b1e007e48cff63449a5e9f4e7ebea716b4111f9c4f9a645f91d579bf0c4"}, ] diff --git a/pyproject.toml b/pyproject.toml index fe928ab7a..afcbe1248 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,8 +18,8 @@ click = "<7.2" gitpython = "^3.1.1" mdx_truly_sane_lists = "^1.2" mike = "^0.5.1" -mkdocs = "<1.2" -mkdocs-material = "<5" +mkdocs = "^1.2.1" +mkdocs-material = "^7.1.8" [tool.poetry.dev-dependencies] black = "^21.7b0" From 4bb83d6073c37da1459fd00eebb41e5544e7aea3 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 22:47:39 -0700 Subject: [PATCH 08/35] Use standardized filename for website publishing workflow This is the template workflow filename, which is intended to serve as a unique identifier, and thus must be a bit more verbose. --- ...ublish-docs.yml => deploy-cobra-mkdocs-versioned-poetry.yml} | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename .github/workflows/{publish-docs.yml => deploy-cobra-mkdocs-versioned-poetry.yml} (97%) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml similarity index 97% rename from .github/workflows/publish-docs.yml rename to .github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index bc3273f24..f6775ad84 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -8,9 +8,9 @@ on: - "[0-9]+.[0-9]+.x" paths: - "docs/**" + - ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml" - "docsgen/**" - "cli/**" - - ".github/workflows/publish-docs.yml" # Run on branch or tag creation (will be filtered by the publish-determination job). create: diff --git a/README.md b/README.md index d8f1b3228..af1aadec4 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Publish Nightly Build status](https://github.com/arduino/arduino-lint/actions/workflows/publish-go-nightly-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/publish-go-nightly-task.yml) [![Check Python status](https://github.com/arduino/arduino-lint/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-python-task.yml) [![Check Markdown status](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml) -[![Docs Status](https://github.com/arduino/arduino-lint/workflows/Publish%20documentation/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Publish+documentation) +[![Deploy Website status](https://github.com/arduino/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml) [![Codecov](https://codecov.io/gh/arduino/arduino-lint/branch/main/graph/badge.svg?token=nprqPQMbdh)](https://codecov.io/gh/arduino/arduino-lint) [![Check Prettier Formatting status](https://github.com/arduino/arduino-lint/actions/workflows/check-prettier-formatting-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-prettier-formatting-task.yml) [![Check General Formatting status](https://github.com/arduino/arduino-lint/actions/workflows/check-general-formatting-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-general-formatting-task.yml) From 39611823a38140ad78e2816b7acad2638269ca2d Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 22:53:49 -0700 Subject: [PATCH 09/35] Use standardized name for command reference generation task Thus is the naming convention established in the standardized template project assets. --- Taskfile.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 68f6c7b29..bc07e81ba 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -229,9 +229,9 @@ tasks: docs:generate: desc: Create all generated documentation content deps: - - task: docs:gen + - task: go:cli-docs - docs:gen: + go:cli-docs: desc: Generate command reference dir: ./docsgen cmds: @@ -246,14 +246,14 @@ tasks: docs:build: desc: Build documentation website contents cmds: - - task: docs:gen + - task: go:cli-docs - poetry install --no-root - poetry run mkdocs build --strict docs:publish: desc: Use Mike to build and push versioned docs cmds: - - task: docs:gen + - task: go:cli-docs - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}} docs:serve: From 1073711ba34f6b33fdbe02813b317fa2d8d4e221 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:03:15 -0700 Subject: [PATCH 10/35] Use standardized job/step names in "Deploy Website" workflow These are the naming conventions established in the standardized template workflow. --- .github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index f6775ad84..854ba1e2e 100644 --- a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -1,4 +1,4 @@ -name: Publish documentation +name: Deploy Website on: push: @@ -38,7 +38,7 @@ jobs: if: needs.publish-determination.outputs.result == 'true' steps: - - name: Checkout local repository + - name: Checkout repository uses: actions/checkout@v2 - name: Install Taskfile From 8afb9dceb9647b60fe20031dda3c1b4264b33c7e Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:10:51 -0700 Subject: [PATCH 11/35] Always use `docs:generate` task for documentation generation Even though this project's generated documentation is currently limited to the CLI reference, this might not always be so, and anyway this is intended to follow a universally applicable template. `docs:generate` is an "umbrella" task that collects all the specific documentation generation subtasks a project has, and so it should be used whenever the documentation needs to be generated. --- Taskfile.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index bc07e81ba..bc9581293 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -230,6 +230,8 @@ tasks: desc: Create all generated documentation content deps: - task: go:cli-docs + # Make the formatting consistent with the non-generated Markdown + - task: general:format-prettier go:cli-docs: desc: Generate command reference @@ -241,19 +243,18 @@ tasks: # we invoke `arduino-lint` like this instead of `./arduino-lint` to remove # the `./` chars from the examples - PATH=. arduino-lint ../docs/commands - - task: general:format-prettier docs:build: desc: Build documentation website contents cmds: - - task: go:cli-docs + - task: docs:generate - poetry install --no-root - poetry run mkdocs build --strict docs:publish: desc: Use Mike to build and push versioned docs cmds: - - task: go:cli-docs + - task: docs:generate - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}} docs:serve: From aaa17b49624e330aab7a2593e511d32b439e4dcf Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:15:34 -0700 Subject: [PATCH 12/35] Use standardized `go:cli-docs` task description Sync with the "template" task. --- Taskfile.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Taskfile.yml b/Taskfile.yml index bc9581293..894d32fba 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -234,7 +234,7 @@ tasks: - task: general:format-prettier go:cli-docs: - desc: Generate command reference + desc: Generate command line interface reference documentation dir: ./docsgen cmds: # docs will generate examples using os.Args[0] so we need to call From 3f82e64c338673692b30c7a463aa04185a08ece3 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:17:50 -0700 Subject: [PATCH 13/35] Use taskfile variable in place of hardcoded project name The project name is defined in the `PROJECT_NAME` taskfile variable. In order to make it easier to share task "templates" among projects, this should always be used in place of the project name in the taskfile. --- Taskfile.yml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 894d32fba..414b7e4fb 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -237,12 +237,10 @@ tasks: desc: Generate command line interface reference documentation dir: ./docsgen cmds: - # docs will generate examples using os.Args[0] so we need to call - # the generator `arduino-lint` - - go build -o arduino-lint{{exeExt}} - # we invoke `arduino-lint` like this instead of `./arduino-lint` to remove - # the `./` chars from the examples - - PATH=. arduino-lint ../docs/commands + # Command examples use os.Args[0] so the docs generation binary must have the same filename as the project + - go build -o {{.PROJECT_NAME}}{{exeExt}} + # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples + - PATH=. {{.PROJECT_NAME}} ../docs/commands docs:build: desc: Build documentation website contents From 579896679f750b9ef2e37b0332fbd42e9f882cfd Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:20:52 -0700 Subject: [PATCH 14/35] Update to new website versioning system This new approach to versioning the website uses the workflow as the sole central orchestrator of the documentation deployment system, restricting the role of the Python script (here renamed from "build.py" to "siteversion") to solely to determining the appropriate version for the deployment. Since deployment of the website is the exclusive domain of the automated systems, there is no point in using Task for that operation, so the deployment commands are moved from the taskfile to the workflow. --- .../deploy-cobra-mkdocs-versioned-poetry.yml | 16 +- Taskfile.yml | 6 - docs/build.py | 159 ------------------ docs/siteversion/siteversion.py | 95 +++++++++++ docs/siteversion/tests/__init__.py | 12 ++ docs/siteversion/tests/pytest.ini | 10 ++ docs/siteversion/tests/test_all.py | 33 ++++ 7 files changed, 163 insertions(+), 168 deletions(-) delete mode 100644 docs/build.py create mode 100644 docs/siteversion/siteversion.py create mode 100644 docs/siteversion/tests/__init__.py create mode 100644 docs/siteversion/tests/pytest.ini create mode 100644 docs/siteversion/tests/test_all.py diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index 854ba1e2e..2b1578d31 100644 --- a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -3,6 +3,7 @@ name: Deploy Website on: push: branches: + # Branch to base "dev" website on. Set in siteversion.py also. - main # Release branches have names like 0.8.x, 0.9.x, ... - "[0-9]+.[0-9]+.x" @@ -73,11 +74,20 @@ jobs: - name: Install Python dependencies run: poetry install --no-root + - name: Determine versioning parameters + id: determine-versioning + run: echo "::set-output name=data::$(poetry run python docs/siteversion/siteversion.py)" + - name: Publish documentation - # Determine docs version for the commit pushed and publish accordingly using Mike. - # Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits. + if: fromJson(steps.determine-versioning.outputs.data).version != null run: | + # Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits. git config --global user.email "bot@arduino.cc" git config --global user.name "ArduinoBot" git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages - poetry run python docs/build.py + poetry run mike deploy \ + --update-aliases \ + --push \ + --remote origin \ + ${{ fromJson(steps.determine-versioning.outputs.data).version }} \ + ${{ fromJson(steps.determine-versioning.outputs.data).alias }} diff --git a/Taskfile.yml b/Taskfile.yml index 414b7e4fb..bcc2b5d2b 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -249,12 +249,6 @@ tasks: - poetry install --no-root - poetry run mkdocs build --strict - docs:publish: - desc: Use Mike to build and push versioned docs - cmds: - - task: docs:generate - - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}} - docs:serve: desc: Run documentation website locally cmds: diff --git a/docs/build.py b/docs/build.py deleted file mode 100644 index e9f861cf7..000000000 --- a/docs/build.py +++ /dev/null @@ -1,159 +0,0 @@ -# This file is part of Arduino Lint. - -# Copyright 2020 ARDUINO SA (http://www.arduino.cc/) - -# This software is released under the GNU General Public License version 3, -# which covers the main part of Arduino Lint. -# The terms of this license can be found at: -# https://www.gnu.org/licenses/gpl-3.0.en.html - -# You can be released from the requirements of the above licenses by purchasing -# a commercial license. Buying such a license is mandatory if you want to -# modify or otherwise use the software for commercial activities involving the -# Arduino software without disclosing the source code of your own applications. -# To purchase a commercial license, send an email to license@arduino.cc. -import os -import sys -import re -import unittest -import subprocess - -import click -from git import Repo - -# In order to provide support for multiple Arduino Lint releases, Documentation is versioned so that visitors can select -# which version of the documentation website should be displayed. Unfortunately this feature isn't provided by GitHub -# pages or MkDocs, so we had to implement it on top of the generation process. -# -# Before delving into the details of the generation process, here follow some requirements that were established to -# provide versioned documentation: -# -# - A special version of the documentation called `dev` is provided to reflect the status of Arduino Lint on the -# `main` branch - this includes unreleased features and bugfixes. -# - Docs are versioned after the minor version of an Arduino Lint release. For example, Arduino Lint `0.99.1` and -# `0.99.2` will be both covered by documentation version `0.99`. -# - The landing page of the documentation website will automatically redirect visitors to the documentation of the most -# recently released version of Arduino Lint. -# -# To implement the requirements above, the execution of MkDocs is wrapped using a CLI tool called Mike -# (https://github.com/jimporter/mike) that does a few things for us: -# -# - It runs MkDocs targeting subfolders named after the Arduino Lint version, e.g. documentation for version `0.10.1` -# can be found under the folder `0.10`. -# - It injects an HTML control into the documentation website that lets visitors choose which version of the docs to -# browse from a dropdown list. -# - It provides a redirect to a version we decide when visitors hit the landing page of the documentation website. -# - It pushes generated contents to the `gh-pages` branch. -# -# In order to avoid unwanted changes to the public website hosting the Arduino Lint documentation, only Mike is allowed -# to push changes to the `gh-pages` branch, and this only happens from within the CI, in the "Publish documentation" -# workflow: https://github.com/arduino/arduino-lint/blob/main/.github/workflows/publish-docs.yml -# -# The CI is responsible for guessing which version of Arduino Lint we're building docs for, so that generated content -# will be stored in the appropriate section of the documentation website. Because this guessing might be fairly complex, -# the logic is implemented in this Python script. The script will determine the version of Arduino Lint that was -# modified in the current commit (either `dev` or an official, numbered release) and whether the redirect to the latest -# version that happens on the landing page should be updated or not. - - -DEV_BRANCHES = ["main"] - - -class TestScript(unittest.TestCase): - def test_get_docs_version(self): - ver, alias = get_docs_version("main", []) - self.assertEqual(ver, "dev") - self.assertEqual(alias, "") - - release_names = ["1.4.x", "0.13.x"] - ver, alias = get_docs_version("0.13.x", release_names) - self.assertEqual(ver, "0.13") - self.assertEqual(alias, "") - ver, alias = get_docs_version("1.4.x", release_names) - self.assertEqual(ver, "1.4") - self.assertEqual(alias, "latest") - - ver, alias = get_docs_version("0.1.x", []) - self.assertIsNone(ver) - self.assertIsNone(alias) - - -def get_docs_version(ref_name, release_branches): - if ref_name in DEV_BRANCHES: - return "dev", "" - - if ref_name in release_branches: - # if version is latest, add an alias - alias = "latest" if ref_name == release_branches[0] else "" - # strip `.x` suffix from the branch name to get the version: 0.3.x -> 0.3 - return ref_name[:-2], alias - - return None, None - - -def get_rel_branch_names(blist): - """Get the names of the release branches, sorted from newest to older. - - Only process remote refs so we're sure to get all of them and clean up the - name so that we have a list of strings like 0.6.x, 0.7.x, ... - """ - pattern = re.compile(r"origin/(\d+\.\d+\.x)") - names = [] - for b in blist: - res = pattern.search(b.name) - if res is not None: - names.append(res.group(1)) - - # Since sorting is stable, first sort by major... - names = sorted(names, key=lambda x: int(x.split(".")[0]), reverse=True) - # ...then by minor - return sorted(names, key=lambda x: int(x.split(".")[1]), reverse=True) - - -@click.command() -@click.option("--test", is_flag=True) -@click.option("--dry", is_flag=True) -@click.option("--remote", default="origin", help="The git remote where to push.") -def main(test, dry, remote): - # Run tests if requested - if test: - unittest.main(argv=[""], exit=False) - sys.exit(0) - - # Detect repo root folder - here = os.path.dirname(os.path.realpath(__file__)) - repo_dir = os.path.join(here, "..") - - # Get current repo - repo = Repo(repo_dir) - - # Get the list of release branch names - rel_br_names = get_rel_branch_names(repo.refs) - - # Deduce docs version from current branch. Use the 'latest' alias if - # version is the most recent - docs_version, alias = get_docs_version(repo.active_branch.name, rel_br_names) - if docs_version is None: - print(f"Can't get version from current branch '{repo.active_branch}', skip docs generation") - return 0 - - # Taskfile args aren't regular args so we put everything in one string - cmd = (f"task docs:publish DOCS_REMOTE={remote} DOCS_VERSION={docs_version} DOCS_ALIAS={alias}",) - - if dry: - print(cmd) - return 0 - - subprocess.run(cmd, shell=True, check=True, cwd=repo_dir) - - -# Usage: -# -# To run the tests: -# $python build.py test -# -# To run the script (must be run from within the repo tree): -# $python build.py -# -if __name__ == "__main__": - sys.exit(main()) diff --git a/docs/siteversion/siteversion.py b/docs/siteversion/siteversion.py new file mode 100644 index 000000000..ce22108e7 --- /dev/null +++ b/docs/siteversion/siteversion.py @@ -0,0 +1,95 @@ +# Source: +# https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/siteversion/siteversion.py + +# Copyright 2020 ARDUINO SA (http://www.arduino.cc/) + +# This software is released under the GNU General Public License version 3 +# The terms of this license can be found at: +# https://www.gnu.org/licenses/gpl-3.0.en.html + +# You can be released from the requirements of the above licenses by purchasing +# a commercial license. Buying such a license is mandatory if you want to +# modify or otherwise use the software for commercial activities involving the +# Arduino software without disclosing the source code of your own applications. +# To purchase a commercial license, send an email to license@arduino.cc. +import os +import re +import json + +from git import Repo + +# In order to provide support for multiple project releases, Documentation is versioned so that visitors can select +# which version of the documentation website should be displayed. Unfortunately this feature isn't provided by GitHub +# pages or MkDocs, so we had to implement it on top of the generation process. +# +# - A special version of the documentation called `dev` is provided to reflect the status of the project on the +# default branch - this includes unreleased features and bugfixes. +# - Docs are versioned after the minor version of a release. For example, release version `0.99.1` and +# `0.99.2` will be both covered by documentation version `0.99`. +# +# The CI is responsible for guessing which version of the project we're building docs for, so that generated content +# will be stored in the appropriate section of the documentation website. Because this guessing might be fairly complex, +# the logic is implemented in this Python script. The script will determine the version of the project that was +# modified in the current commit (either `dev` or an official, numbered release) and whether the redirect to the latest +# version that happens on the landing page should be updated or not. + + +DEV_BRANCHES = ["main"] # Name of the branch used for the "dev" website source content + + +def get_docs_version(ref_name, release_branches): + if ref_name in DEV_BRANCHES: + return {"version": "dev", "alias": ""} + + if ref_name in release_branches: + # if version is latest, add an alias + alias = "latest" if ref_name == release_branches[0] else "" + # strip `.x` suffix from the branch name to get the version: 0.3.x -> 0.3 + return {"version": ref_name[:-2], "alias": alias} + + return {"version": None, "alias": None} + + +def get_rel_branch_names(blist): + """Get the names of the release branches, sorted from newest to older. + + Only process remote refs so we're sure to get all of them and clean up the + name so that we have a list of strings like 0.6.x, 0.7.x, ... + """ + pattern = re.compile(r"origin/(\d+\.\d+\.x)") + names = [] + for b in blist: + res = pattern.search(b.name) + if res is not None: + names.append(res.group(1)) + + # Since sorting is stable, first sort by major... + names = sorted(names, key=lambda x: int(x.split(".")[0]), reverse=True) + # ...then by minor + return sorted(names, key=lambda x: int(x.split(".")[1]), reverse=True) + + +def main(): + # Detect repo root folder + here = os.path.dirname(os.path.realpath(__file__)) + repo_dir = os.path.join(here, "..", "..") + + # Get current repo + repo = Repo(repo_dir) + + # Get the list of release branch names + rel_br_names = get_rel_branch_names(repo.refs) + + # Deduce docs version from current branch. + versioning_data = get_docs_version(repo.active_branch.name, rel_br_names) + + # Return the data as JSON on stdout + print(json.dumps(versioning_data)) + + +# Usage: +# To run the script (must be run from within the repo tree): +# $python siteversion.py +# +if __name__ == "__main__": + main() diff --git a/docs/siteversion/tests/__init__.py b/docs/siteversion/tests/__init__.py new file mode 100644 index 000000000..b353c4a01 --- /dev/null +++ b/docs/siteversion/tests/__init__.py @@ -0,0 +1,12 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-python/__init__.py +# Copyright 2021 ARDUINO SA (http://www.arduino.cc/) +# +# This software is released under the GNU General Public License version 3, +# The terms of this license can be found at: +# https: // www.gnu.org/licenses/gpl-3.0.en.html +# +# You can be released from the requirements of the above licenses by purchasing +# a commercial license. Buying such a license is mandatory if you want to +# modify or otherwise use the software for commercial activities involving the +# Arduino software without disclosing the source code of your own applications. +# To purchase a commercial license, send an email to license@arduino.cc. diff --git a/docs/siteversion/tests/pytest.ini b/docs/siteversion/tests/pytest.ini new file mode 100644 index 000000000..b8beed3fa --- /dev/null +++ b/docs/siteversion/tests/pytest.ini @@ -0,0 +1,10 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-python/pytest.ini +[pytest] +filterwarnings = + error + ignore::DeprecationWarning + ignore::ResourceWarning + +# --capture=no - disable per-test capture +# --tb=long sets the length of the traceback in case of failures +addopts = --capture=no --tb=long --verbose diff --git a/docs/siteversion/tests/test_all.py b/docs/siteversion/tests/test_all.py new file mode 100644 index 000000000..eb66ea7e2 --- /dev/null +++ b/docs/siteversion/tests/test_all.py @@ -0,0 +1,33 @@ +# Source: +# https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/siteversion/test/test_all.py + +# Copyright 2020 ARDUINO SA (http://www.arduino.cc/) + +# This software is released under the GNU General Public License version 3 +# The terms of this license can be found at: +# https://www.gnu.org/licenses/gpl-3.0.en.html + +# You can be released from the requirements of the above licenses by purchasing +# a commercial license. Buying such a license is mandatory if you want to +# modify or otherwise use the software for commercial activities involving the +# Arduino software without disclosing the source code of your own applications. +# To purchase a commercial license, send an email to license@arduino.cc. +import siteversion + + +def test_get_docs_version(): + data = siteversion.get_docs_version("main", []) + assert data["version"] == "dev" + assert data["alias"] == "" + + release_names = ["1.4.x", "0.13.x"] + data = siteversion.get_docs_version("0.13.x", release_names) + assert data["version"] == "0.13" + assert data["alias"] == "" + data = siteversion.get_docs_version("1.4.x", release_names) + assert data["version"] == "1.4" + assert data["alias"] == "latest" + + data = siteversion.get_docs_version("0.1.x", []) + assert data["version"] is None + assert data["alias"] is None From 9afdaa145e8b642e973897967932c43b8a5d7fa6 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:30:55 -0700 Subject: [PATCH 15/35] Expand "Deploy Website" workflow's paths filter to cover all relevant files The paths filter is used to make GitHub Actions workflows more efficient and contributor friendly by preventing pointless workflow runs from happening when only irrelevant files were modified. However, careful consideration must be given to which files are relevant. --- .../workflows/deploy-cobra-mkdocs-versioned-poetry.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index 2b1578d31..7daf9ec17 100644 --- a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -10,8 +10,14 @@ on: paths: - "docs/**" - ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml" + - "go.mod" + - "go.sum" + - "Taskfile.ya?ml" + - "**.go" - "docsgen/**" - - "cli/**" + - "mkdocs.ya?ml" + - "poetry.lock" + - "pyproject.toml" # Run on branch or tag creation (will be filtered by the publish-determination job). create: From dd9dcc169fadb85bc3a0d931a8bb8480f853892a Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:34:34 -0700 Subject: [PATCH 16/35] Order "Deploy Website" workflow's steps according to the template No functional difference, and neither is necessarily superior, but that is how it is in the template, and so it must be here too. --- .../deploy-cobra-mkdocs-versioned-poetry.yml | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index 7daf9ec17..55072869e 100644 --- a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -48,17 +48,6 @@ jobs: - name: Checkout repository uses: actions/checkout@v2 - - name: Install Taskfile - uses: arduino/setup-task@v1 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - version: 3.x - - - name: Install Go - uses: actions/setup-go@v2 - with: - go-version: "1.14" - - name: Install Python uses: actions/setup-python@v2 with: @@ -77,6 +66,15 @@ jobs: python -m pip install --upgrade pip python -m pip install poetry + - name: Install Task + uses: arduino/setup-task@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + version: 3.x + + - name: Create all generated documentation content + run: task docs:generate + - name: Install Python dependencies run: poetry install --no-root From 0b16b1cb7ea39e284ec58a090e570addeac32bca Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:36:15 -0700 Subject: [PATCH 17/35] Remove Python dependencies caching step During the development phase of the previous attempt at setting up an official collection of template workflows, I investigated dependencies caching and added it to all workflows where applicable. Afterwards, doubts were raised about whether it provided any benefits. I don't know enough about this subject to make a call on that and I have been unable to get any more information on the subject. Since the caching significantly increases the complexity of the workflows, which may make them more difficult to maintain and contribute to, I think it's best to just remove all the caching for now. I hope to eventually be able to revisit this topic and restore caching in any workflows where it is definitely beneficial. This particular caching step was in the source workflow in the Arduino CLI repository from the very beginning, and was my inspiration for using caching in the first place. However, none of the other workflows with Python dependencies have caching at this point, so having this one as an exception to the otherwise fairly standardized workflow format is confusing. --- .../workflows/deploy-cobra-mkdocs-versioned-poetry.yml | 8 -------- .github/workflows/validate-docs.yml | 8 -------- 2 files changed, 16 deletions(-) diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index 55072869e..0ba808f36 100644 --- a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -53,14 +53,6 @@ jobs: with: python-version: "3.9" - - name: Cache dependencies - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- - - name: Install Poetry run: | python -m pip install --upgrade pip diff --git a/.github/workflows/validate-docs.yml b/.github/workflows/validate-docs.yml index 5cd2a9b3c..536db9287 100644 --- a/.github/workflows/validate-docs.yml +++ b/.github/workflows/validate-docs.yml @@ -43,14 +43,6 @@ jobs: with: python-version: "3.9" - - name: Cache dependencies - uses: actions/cache@v2 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- - - name: Install Poetry run: | python -m pip install --upgrade pip From e72436f91b1ed9f0dbc1fc39ec539cff77596ca4 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:38:09 -0700 Subject: [PATCH 18/35] Remove project-specific references from "docsgen" program's comments This is a standardized "template" program that is intended to be added to any project with the minimum of changes. The project specific references are unnecessary and some even were not updated when the file was copied from its original source in the Arduino CLI repository. --- docsgen/main.go | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docsgen/main.go b/docsgen/main.go index 1f907075b..6705a6f84 100644 --- a/docsgen/main.go +++ b/docsgen/main.go @@ -1,9 +1,7 @@ -// This file is part of arduino-cli. // // Copyright 2020 ARDUINO SA (http://www.arduino.cc/) // -// This software is released under the GNU General Public License version 3, -// which covers the main part of arduino-cli. +// This software is released under the GNU General Public License version 3. // The terms of this license can be found at: // https://www.gnu.org/licenses/gpl-3.0.en.html // @@ -13,7 +11,7 @@ // Arduino software without disclosing the source code of your own applications. // To purchase a commercial license, send an email to license@arduino.cc. -// Package main generates Markdown documentation for the Arduino Lint CLI. +// Package main generates Markdown documentation for the project's CLI. package main import ( From fa0506f732c064ee5a3bee6da98f226c3123e424 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:40:56 -0700 Subject: [PATCH 19/35] Generate the Cobra docs output folder on demand The command line reference documentation for Cobra-based Go projects is output to the docs/commands/ folder. Since this documentation is generated, it is not stored in the repository. Previously, the generation program required this output folder to already exist. This meant that the otherwise empty folder had to be added to the repository, with a `.gitkeep` placeholder file since Git does not track empty folders in repositories. This added clutter to the repository. A better approach is for the documentation generation program to simply create the output folder before generating the content. --- docs/commands/.gitkeep | 0 docsgen/main.go | 2 ++ 2 files changed, 2 insertions(+) delete mode 100644 docs/commands/.gitkeep diff --git a/docs/commands/.gitkeep b/docs/commands/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/docsgen/main.go b/docsgen/main.go index 6705a6f84..139f48935 100644 --- a/docsgen/main.go +++ b/docsgen/main.go @@ -27,6 +27,8 @@ func main() { os.Exit(1) } + os.MkdirAll(os.Args[1], 0755) // Create the output folder if it doesn't already exist + cli := cli.Root() cli.DisableAutoGenTag = true // Disable addition of auto-generated date stamp err := doc.GenMarkdownTree(cli, os.Args[1]) From 61990417b0401461404d7b60f21924d1a2e1a453 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:47:51 -0700 Subject: [PATCH 20/35] Use standardized name for website check tasks Thus is the naming convention established in the standardized template project assets. --- .github/workflows/validate-docs.yml | 2 +- Taskfile.yml | 4 ++-- docs/CONTRIBUTING.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/validate-docs.yml b/.github/workflows/validate-docs.yml index 536db9287..1c27a4cbf 100644 --- a/.github/workflows/validate-docs.yml +++ b/.github/workflows/validate-docs.yml @@ -50,4 +50,4 @@ jobs: - name: Build documentation website # Ensure the documentation can build. These docs won't be published. - run: task docs:build + run: task website:check diff --git a/Taskfile.yml b/Taskfile.yml index bcc2b5d2b..27a21c7be 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -242,14 +242,14 @@ tasks: # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples - PATH=. {{.PROJECT_NAME}} ../docs/commands - docs:build: + website:check: desc: Build documentation website contents cmds: - task: docs:generate - poetry install --no-root - poetry run mkdocs build --strict - docs:serve: + website:serve: desc: Run documentation website locally cmds: - task: docs:build diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index bea7ee92c..26821b8a1 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -232,7 +232,7 @@ documentation website. You can build the documentation website and serve it from command: ``` -task docs:serve +task website:serve ``` The documentation will build. If you don't see any error, open `http://127.0.0.1:8000` in your browser to local the @@ -254,7 +254,7 @@ Otherwise you can use the following tasks. To do so you'll need to install `npm` To check if the files are correctly formatted run: ```shell -task docs:check +task website:check ``` If the output tells you that some files are not formatted correctly run: From 49854d2c77394e886b480bb0438f2a2cb8288e6e Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:48:44 -0700 Subject: [PATCH 21/35] Use standardized descriptions for website check tasks Sync with "template" tasks. --- Taskfile.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 27a21c7be..807c13cdb 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -243,14 +243,14 @@ tasks: - PATH=. {{.PROJECT_NAME}} ../docs/commands website:check: - desc: Build documentation website contents + desc: Check whether the MkDocs-based website will build cmds: - task: docs:generate - poetry install --no-root - poetry run mkdocs build --strict website:serve: - desc: Run documentation website locally + desc: Run website locally cmds: - task: docs:build - poetry run mkdocs serve From 2e5218d7220b67dc37e52eefe1c0959171228d20 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:55:17 -0700 Subject: [PATCH 22/35] Use Python dependency installation task in `website:check` A dedicated task has been added for installing the project's Python depencies, and this should be used throughout the taskfile in place of redundant direct commands. --- Taskfile.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Taskfile.yml b/Taskfile.yml index 807c13cdb..b38c50f31 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -246,7 +246,7 @@ tasks: desc: Check whether the MkDocs-based website will build cmds: - task: docs:generate - - poetry install --no-root + - task: poetry:install-deps - poetry run mkdocs build --strict website:serve: From 0c066bb25f95ccb51dbba71233afbe25648c7f06 Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:57:47 -0700 Subject: [PATCH 23/35] Move dependencies to the `website:check` task's `deps` key This allows the dependency tasks to run in parallel. --- Taskfile.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Taskfile.yml b/Taskfile.yml index b38c50f31..e766ef490 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -244,9 +244,10 @@ tasks: website:check: desc: Check whether the MkDocs-based website will build - cmds: + deps: - task: docs:generate - task: poetry:install-deps + cmds: - poetry run mkdocs build --strict website:serve: From 2f257e89bed3a26940e5e759567944f4a0170e4c Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 3 Aug 2021 23:59:33 -0700 Subject: [PATCH 24/35] Avoid redundant website build in `website:serve` task The `mkdocs serve` command builds the website before serving it, so it is not necessary to do a run of `mkdocs build` first. --- Taskfile.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Taskfile.yml b/Taskfile.yml index e766ef490..e22892826 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -252,8 +252,10 @@ tasks: website:serve: desc: Run website locally + deps: + - task: docs:generate + - task: poetry:install-deps cmds: - - task: docs:build - poetry run mkdocs serve docs:check: From 5a790c2699e157aef7a3a464b155900db79d871b Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:09:17 -0700 Subject: [PATCH 25/35] Use standardized filename for website check workflow This is the template workflow filename, which is intended to serve as a unique identifier, and thus must be a bit more verbose. --- .../workflows/{validate-docs.yml => check-mkdocs-task.yml} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename .github/workflows/{validate-docs.yml => check-mkdocs-task.yml} (91%) diff --git a/.github/workflows/validate-docs.yml b/.github/workflows/check-mkdocs-task.yml similarity index 91% rename from .github/workflows/validate-docs.yml rename to .github/workflows/check-mkdocs-task.yml index 1c27a4cbf..38e71b427 100644 --- a/.github/workflows/validate-docs.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -10,14 +10,14 @@ on: # potential changes to commands documentation - "cli/**" # changes to the workflow itself - - ".github/workflows/validate-docs.yml" + - ".github/workflows/check-mkdocs-task.ya?ml" push: paths: - "docs/**" - "docsgen/**" - "cli/**" - "rpc/**" - - ".github/workflows/validate-docs.yml" + - ".github/workflows/check-mkdocs-task.ya?ml" jobs: validate: From 50d953bb38b29c8aa74789f42b9fc5906f7d113b Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:14:30 -0700 Subject: [PATCH 26/35] Use standardized workflow/job/step names in website check workflow These are the naming conventions established in the standardized template workflow. --- .github/workflows/check-mkdocs-task.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index 38e71b427..c5582c2b2 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -1,4 +1,4 @@ -name: Validate documentation +name: Check Website on: pull_request: @@ -20,14 +20,14 @@ on: - ".github/workflows/check-mkdocs-task.ya?ml" jobs: - validate: + check: runs-on: ubuntu-latest steps: - - name: Checkout local repository + - name: Checkout repository uses: actions/checkout@v2 - - name: Install Taskfile + - name: Install Task uses: arduino/setup-task@v1 with: repo-token: ${{ secrets.GITHUB_TOKEN }} @@ -48,6 +48,6 @@ jobs: python -m pip install --upgrade pip python -m pip install poetry - - name: Build documentation website + - name: Build website # Ensure the documentation can build. These docs won't be published. run: task website:check From 86a8a031b70cbdc33927b736e7f74ed4c8a895d8 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:18:03 -0700 Subject: [PATCH 27/35] Expand "Check Website" workflow's paths filter to cover all relevant files The paths filter is used to make GitHub Actions workflows more efficient and contributor friendly by preventing pointless workflow runs from happening when only irrelevant files were modified. However, careful consideration must be given to which files are relevant. --- .github/workflows/check-mkdocs-task.yml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index c5582c2b2..8906d0870 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -3,21 +3,24 @@ name: Check Website on: pull_request: paths: - # existing docs + - ".github/workflows/check-mkdocs-task.ya?ml" + - "Taskfile.ya?ml" + - "mkdocs.ya?ml" + - "poetry.lock" + - "pyproject.toml" - "docs/**" - # changes to the cli reference generator - "docsgen/**" - # potential changes to commands documentation - - "cli/**" - # changes to the workflow itself - - ".github/workflows/check-mkdocs-task.ya?ml" + - "**.go" push: paths: + - ".github/workflows/check-mkdocs-task.ya?ml" + - "Taskfile.ya?ml" + - "mkdocs.ya?ml" + - "poetry.lock" + - "pyproject.toml" - "docs/**" - "docsgen/**" - - "cli/**" - - "rpc/**" - - ".github/workflows/check-mkdocs-task.ya?ml" + - "**.go" jobs: check: From cab4e859a3f37d7da8d628a2a3d20759fdf7d70c Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:18:32 -0700 Subject: [PATCH 28/35] Sync "Check Website" workflow's trigger order with the template No functional change, and neither is necessarily superior, but this is how it is in the template, and so it must be here as well. --- .github/workflows/check-mkdocs-task.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index 8906d0870..6e492fe94 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -1,7 +1,7 @@ name: Check Website on: - pull_request: + push: paths: - ".github/workflows/check-mkdocs-task.ya?ml" - "Taskfile.ya?ml" @@ -11,7 +11,7 @@ on: - "docs/**" - "docsgen/**" - "**.go" - push: + pull_request: paths: - ".github/workflows/check-mkdocs-task.ya?ml" - "Taskfile.ya?ml" From 8301006f46b282af49b5ce950ced3c9de85f893a Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:20:15 -0700 Subject: [PATCH 29/35] Add manual events as "Check Website" workflow triggers The `workflow_dispatch` event allows triggering the workflow via the GitHub web interface. This makes it easy to trigger an immediate workflow run after some relevant external change. The `repository_dispatch` event allows triggering workflows via the GitHub API. This might be useful for triggering an immediate check in multiple relevant repositories after an external change, or some automated process. Although we don't have any specific need for this event at the moment, the event has no impact on the workflow, so there is no reason against having it. It is the sort of thing that can end up being useful if it is already in consistently in place, but not worth setting up on demand, since the effort to set it up is greater than the effort to trigger all the workflows manually. --- .github/workflows/check-mkdocs-task.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index 6e492fe94..d80f88f2b 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -1,5 +1,6 @@ name: Check Website +# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows on: push: paths: @@ -21,6 +22,8 @@ on: - "docs/**" - "docsgen/**" - "**.go" + workflow_dispatch: + repository_dispatch: jobs: check: From d35d30b58021adb1a420cef7d4ccec41442c4a71 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:21:32 -0700 Subject: [PATCH 30/35] Order "Check Website" workflow's steps according to the template No functional difference, and neither is necessarily superior, but that is how it is in the template, and so it must be here too. --- .github/workflows/check-mkdocs-task.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index d80f88f2b..a962cea34 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -33,12 +33,6 @@ jobs: - name: Checkout repository uses: actions/checkout@v2 - - name: Install Task - uses: arduino/setup-task@v1 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - version: 3.x - - name: Install Go uses: actions/setup-go@v2 with: @@ -54,6 +48,12 @@ jobs: python -m pip install --upgrade pip python -m pip install poetry + - name: Install Task + uses: arduino/setup-task@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + version: 3.x + - name: Build website # Ensure the documentation can build. These docs won't be published. run: task website:check From 10d2e59bd075294b9b16fc377f9faffa6584ffdd Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:22:03 -0700 Subject: [PATCH 31/35] Remove pip update command from "Check Website" workflow I'm actually not sure that this is an improvement, but it's this way in the template, so it's best to just sync it for now and hopefully take a closer look at some point in the future. --- .github/workflows/check-mkdocs-task.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index a962cea34..bebb414af 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -44,9 +44,7 @@ jobs: python-version: "3.9" - name: Install Poetry - run: | - python -m pip install --upgrade pip - python -m pip install poetry + run: pip install poetry - name: Install Task uses: arduino/setup-task@v1 From dc1dd59b8b45174c2342a76894180d226f02a013 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:23:25 -0700 Subject: [PATCH 32/35] Remove superfluous comment from "Check Website" workflow --- .github/workflows/check-mkdocs-task.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index bebb414af..2e891b10f 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -53,5 +53,4 @@ jobs: version: 3.x - name: Build website - # Ensure the documentation can build. These docs won't be published. run: task website:check From 82cfc787c9efca0b4ea39fb02434cdd5b4fbd4ff Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:24:11 -0700 Subject: [PATCH 33/35] Add "Check Website" workflow badge to readme The badges provide a prominent indication of the repository's CI status at a glance. This may help to bring potential issues to the attention of the maintainers. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index af1aadec4..135a3f55e 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ [![Publish Nightly Build status](https://github.com/arduino/arduino-lint/actions/workflows/publish-go-nightly-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/publish-go-nightly-task.yml) [![Check Python status](https://github.com/arduino/arduino-lint/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-python-task.yml) [![Check Markdown status](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml) +[![Check Website status](https://github.com/arduino/arduino-lint/actions/workflows/check-mkdocs-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-mkdocs-task.yml) [![Deploy Website status](https://github.com/arduino/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml) [![Codecov](https://codecov.io/gh/arduino/arduino-lint/branch/main/graph/badge.svg?token=nprqPQMbdh)](https://codecov.io/gh/arduino/arduino-lint) [![Check Prettier Formatting status](https://github.com/arduino/arduino-lint/actions/workflows/check-prettier-formatting-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-prettier-formatting-task.yml) From 771321259982b83405cd6b1a3c5f0f13d2ddd330 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:24:39 -0700 Subject: [PATCH 34/35] Add source URL comments to website assets This will make it easier for the maintainers to sync fixes and improvements in either direction between the upstream "template" assets and their installations in this repository. --- .github/workflows/check-mkdocs-task.yml | 1 + .github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml | 1 + Taskfile.yml | 4 ++++ docsgen/go.mod | 1 + docsgen/main.go | 1 + mkdocs.yml | 1 + 6 files changed, 9 insertions(+) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index 2e891b10f..4889632c7 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -1,3 +1,4 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-mkdocs-task.md name: Check Website # See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml index 0ba808f36..37726cb8f 100644 --- a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml +++ b/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -1,3 +1,4 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md name: Deploy Website on: diff --git a/Taskfile.yml b/Taskfile.yml index e22892826..1920bcd52 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -226,6 +226,7 @@ tasks: cmds: - poetry run black . + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml docs:generate: desc: Create all generated documentation content deps: @@ -233,6 +234,7 @@ tasks: # Make the formatting consistent with the non-generated Markdown - task: general:format-prettier + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml go:cli-docs: desc: Generate command line interface reference documentation dir: ./docsgen @@ -242,6 +244,7 @@ tasks: # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples - PATH=. {{.PROJECT_NAME}} ../docs/commands + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml website:check: desc: Check whether the MkDocs-based website will build deps: @@ -250,6 +253,7 @@ tasks: cmds: - poetry run mkdocs build --strict + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml website:serve: desc: Run website locally deps: diff --git a/docsgen/go.mod b/docsgen/go.mod index 004cec49b..6a1f49b14 100644 --- a/docsgen/go.mod +++ b/docsgen/go.mod @@ -1,3 +1,4 @@ +// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/cobra/docsgen/go.mod module github.com/arduino/arduino-lint/docsgen go 1.16 diff --git a/docsgen/main.go b/docsgen/main.go index 139f48935..2d08b349a 100644 --- a/docsgen/main.go +++ b/docsgen/main.go @@ -1,3 +1,4 @@ +// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/cobra/docsgen/main.go // // Copyright 2020 ARDUINO SA (http://www.arduino.cc/) // diff --git a/mkdocs.yml b/mkdocs.yml index 96feaa79d..75ac2aa27 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,4 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/mkdocs/mkdocs.yml # See: https://www.mkdocs.org/user-guide/configuration/ site_name: Arduino Lint site_description: Tool to check for problems with Arduino projects From 8a06ac36668a3a768c61464b0d182a231a5e9120 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 4 Aug 2021 00:27:10 -0700 Subject: [PATCH 35/35] Use workflow variables for tool versions in "Check Website" workflow Placement of this information at the top of the file, where it is easy to find and edit, facilitates updates to the workflows as the tool version used for project development are bumped periodically. --- .github/workflows/check-mkdocs-task.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check-mkdocs-task.yml b/.github/workflows/check-mkdocs-task.yml index 4889632c7..dd317fbdc 100644 --- a/.github/workflows/check-mkdocs-task.yml +++ b/.github/workflows/check-mkdocs-task.yml @@ -1,6 +1,12 @@ # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-mkdocs-task.md name: Check Website +env: + # See: https://github.com/actions/setup-go/tree/v2#readme + GO_VERSION: "1.14" + # See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python + PYTHON_VERSION: "3.9" + # See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows on: push: @@ -37,12 +43,12 @@ jobs: - name: Install Go uses: actions/setup-go@v2 with: - go-version: "1.14" + go-version: ${{ env.GO_VERSION }} - name: Install Python uses: actions/setup-python@v2 with: - python-version: "3.9" + python-version: ${{ env.PYTHON_VERSION }} - name: Install Poetry run: pip install poetry