From 0d661b743b91cc0bc656bf31bd7945d6fe9d2473 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 12:35:38 +0200 Subject: [PATCH 1/7] config git in publish step, remove magic string from build script --- .github/workflows/docs.yaml | 6 +++++- docs/build.py | 5 ++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index d38a9513e72..674bc307839 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -14,6 +14,7 @@ on: push: branches: - master + - massi/publish # release branches have names like 0.8.x, 0.9.x, ... - '[0-9]+.[0-9]+.x' # At this day, GitHub doesn't support YAML anchors, d'oh! @@ -81,4 +82,7 @@ jobs: if: github.event_name == 'push' env: REMOTE: https://x-access-token:${{secrets.GITHUB_TOKEN}}@github.com/${{github.repository}}.git - run: python docs/build.py + run: | + git config --global user.email "bot@arduino.cc" + git config --global user.name "ArduinoBot" + python docs/build.py diff --git a/docs/build.py b/docs/build.py index 1066bce0bc7..00713073b79 100644 --- a/docs/build.py +++ b/docs/build.py @@ -21,6 +21,9 @@ from git import Repo +DEV_BRANCHES = ["master", "massi/publish"] + + class TestScript(unittest.TestCase): def test_get_docs_version(self): ver, alias = get_docs_version("master", []) @@ -41,7 +44,7 @@ def test_get_docs_version(self): def get_docs_version(ref_name, release_branches): - if ref_name == "master": + if ref_name in DEV_BRANCHES: return "dev", "" if ref_name in release_branches: From 1ba862dcddfb463a8a64052cbaf0c5f23899d8f1 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 14:53:04 +0200 Subject: [PATCH 2/7] expand build.py CLI to simplify action's code --- .github/workflows/docs.yaml | 5 ++-- Taskfile.yml | 2 +- docs/build.py | 46 +++++++++++++++++++------------------ requirements_docs.txt | 3 ++- 4 files changed, 29 insertions(+), 27 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 674bc307839..0520d3b3155 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -80,9 +80,8 @@ jobs: - name: Publish docs # determine docs version for the commit pushed and publish accordingly using Mike if: github.event_name == 'push' - env: - REMOTE: https://x-access-token:${{secrets.GITHUB_TOKEN}}@github.com/${{github.repository}}.git run: | git config --global user.email "bot@arduino.cc" git config --global user.name "ArduinoBot" - python docs/build.py + git remote add upstream https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git + python docs/build.py --remote upstream diff --git a/Taskfile.yml b/Taskfile.yml index 774fac6abdd..64282302b55 100755 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -40,7 +40,7 @@ tasks: - docs:gen:commands - docs:gen:protobuf cmds: - - mike deploy -r {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}} + - mike deploy -p -r {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}} docs:serve: desc: Run documentation website locally diff --git a/docs/build.py b/docs/build.py index 00713073b79..19232d0d0bd 100644 --- a/docs/build.py +++ b/docs/build.py @@ -18,6 +18,7 @@ import unittest import subprocess +import click from git import Repo @@ -75,11 +76,19 @@ def get_rel_branch_names(blist): return sorted(names, key=lambda x: int(x.split(".")[1]), reverse=True) -def main(repo_dir): - # Git remote must be set to publish docs - remote = os.environ.get("REMOTE") - if not remote: - print("REMOTE env var must be set to publish, running dry mode") +@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) @@ -96,18 +105,16 @@ def main(repo_dir): ) return 0 - args = [ - "task docs:publish", - f"DOCS_REMOTE={remote}", - f"DOCS_VERSION={docs_version}", - f"DOCS_ALIAS={alias}", - ] - if remote: - subprocess.run(args, shell=True, check=True, cwd=repo_dir) - else: - print(" ".join(args)) + # 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 - return 0 + subprocess.run(cmd, shell=True, check=True, cwd=repo_dir) # Usage: @@ -119,9 +126,4 @@ def main(repo_dir): # $python build.py # if __name__ == "__main__": - if len(sys.argv) > 1 and sys.argv[1] == "test": - unittest.main(argv=[""], exit=False) - sys.exit(0) - - here = os.path.dirname(os.path.realpath(__file__)) - sys.exit(main(os.path.join(here, ".."))) + sys.exit(main()) diff --git a/requirements_docs.txt b/requirements_docs.txt index a3cdb15d5be..556bfb97e27 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,4 +1,5 @@ mkdocs<1.2 mkdocs-material<5 mike -gitpython \ No newline at end of file +gitpython +click<7.2 \ No newline at end of file From 2656ab7dab1b6cbb3f788a4c40a2d35210acb55d Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 15:26:10 +0200 Subject: [PATCH 3/7] build when workflow changes --- .github/workflows/docs.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 0520d3b3155..43711b66feb 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -11,6 +11,8 @@ on: - 'cli/**' # potential changes to gRPC documentation - 'rpc/**' + # changes to the workflow itself + - '.github/workflows/docs.yaml' push: branches: - master @@ -23,6 +25,7 @@ on: - 'docsgen/**' - 'cli/**' - 'rpc/**' + - '.github/workflows/docs.yaml' jobs: build: From 933316df94c23a646fbfc0f67e3a2669821868b3 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 15:40:55 +0200 Subject: [PATCH 4/7] fetch gh-pages branch --- .github/workflows/docs.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 43711b66feb..054be00d856 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -86,5 +86,6 @@ jobs: run: | 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 git remote add upstream https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git - python docs/build.py --remote upstream + python docs/build.py From f2d921cc3cdc8f6ea0585c2027869f3ec58d8cee Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 16:15:31 +0200 Subject: [PATCH 5/7] fix version selector --- docs/js/version-select.js | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/js/version-select.js b/docs/js/version-select.js index 06a35bf9fee..3c8edca9b09 100644 --- a/docs/js/version-select.js +++ b/docs/js/version-select.js @@ -1,4 +1,4 @@ -window.addEventListener("DOMContentLoaded", function() { +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$"); @@ -12,9 +12,9 @@ window.addEventListener("DOMContentLoaded", function() { var select = document.createElement("select"); select.classList.add("form-control"); - options.forEach(function(i) { + options.forEach(function (i) { var option = new Option(i.text, i.value, undefined, - i.value === selected); + i.value === selected); select.add(option); }); @@ -22,19 +22,19 @@ window.addEventListener("DOMContentLoaded", function() { } var xhr = new XMLHttpRequest(); - xhr.open("GET", REL_BASE_URL + "/../versions.json"); - xhr.onload = function() { + xhr.open("GET", ABS_BASE_URL + "/../versions.json"); + xhr.onload = function () { var versions = JSON.parse(this.responseText); - var realVersion = versions.find(function(i) { + var realVersion = versions.find(function (i) { return i.version === CURRENT_VERSION || - i.aliases.includes(CURRENT_VERSION); + i.aliases.includes(CURRENT_VERSION); }).version; - var select = makeSelect(versions.map(function(i) { - return {text: i.title, value: i.version}; + var select = makeSelect(versions.map(function (i) { + return { text: i.title, value: i.version }; }), realVersion); - select.addEventListener("change", function(event) { + select.addEventListener("change", function (event) { window.location.href = REL_BASE_URL + "/../" + this.value; }); From a64b71819549ece4c21635843b674b1d5cac54c9 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 16:34:53 +0200 Subject: [PATCH 6/7] Remove testing code --- .github/workflows/docs.yaml | 1 - docs/build.py | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 054be00d856..2a01d5863b3 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -16,7 +16,6 @@ on: push: branches: - master - - massi/publish # release branches have names like 0.8.x, 0.9.x, ... - '[0-9]+.[0-9]+.x' # At this day, GitHub doesn't support YAML anchors, d'oh! diff --git a/docs/build.py b/docs/build.py index 19232d0d0bd..d258024c317 100644 --- a/docs/build.py +++ b/docs/build.py @@ -22,7 +22,7 @@ from git import Repo -DEV_BRANCHES = ["master", "massi/publish"] +DEV_BRANCHES = ["master"] class TestScript(unittest.TestCase): From 4b01ec39998a5c3fa3b61ecb15cd3e0cc04aab02 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Thu, 21 May 2020 16:48:01 +0200 Subject: [PATCH 7/7] document who owns commits on gh-pages --- .github/workflows/docs.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 2a01d5863b3..895ee00c2e0 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -74,17 +74,18 @@ jobs: python3 -m pip install -r ./requirements_docs.txt - name: Build docs website - # this runs on every PR to ensure the docs build is sane, these docs + # This runs on every PR to ensure the docs build is sane, these docs # won't be published if: github.event_name == 'pull_request' run: task docs:build - name: Publish docs - # determine docs version for the commit pushed and publish accordingly using Mike + # 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: github.event_name == 'push' run: | 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 - git remote add upstream https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git python docs/build.py