[skip changelog] Configure git push from CI (#717)

* config git in publish step, remove magic string from build script

* expand build.py CLI to simplify action's code

* build when workflow changes

* fetch gh-pages branch

* fix version selector

* Remove testing code

* document who owns commits on gh-pages

Author: Massimiliano Pippi

.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
@@ -22,6 +24,7 @@ on:
       - 'docsgen/**'
       - 'cli/**'
       - 'rpc/**'
+      - '.github/workflows/docs.yaml'
 
 jobs:
   build:
@@ -71,14 +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'
-        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"
+          git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
+          python docs/build.py

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

docs/build.py

@@ -18,9 +18,13 @@
 import unittest
 import subprocess
 
+import click
 from git import Repo
 
 
+DEV_BRANCHES = ["master"]
+
+
 class TestScript(unittest.TestCase):
     def test_get_docs_version(self):
         ver, alias = get_docs_version("master", [])
@@ -41,7 +45,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:
@@ -72,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)
@@ -93,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}",
+    )
 
-    return 0
+    if dry:
+        print(cmd)
+        return 0
+
+    subprocess.run(cmd, shell=True, check=True, cwd=repo_dir)
 
 
 # Usage:
@@ -116,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())

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,29 +12,29 @@ 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);
     });
 
     return select;
   }
 
   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;
     });
 

requirements_docs.txt

@@ -1,4 +1,5 @@
 mkdocs<1.2
 mkdocs-material<5
 mike
-gitpython
+gitpython
+click<7.2