diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index d38a9513e72..895ee00c2e0 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 @@ -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 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 1066bce0bc7..d258024c317 100644 --- a/docs/build.py +++ b/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()) 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; }); 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