-
-
Notifications
You must be signed in to change notification settings - Fork 17
Add CI workflow to deploy a versioned MkDocs-based website to GitHub Pages #64
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
4117d9a
Add CI workflow to deploy a versioned MkDocs-based website to GitHub …
umbynos 972a3d8
applied suggestions by @per1234
umbynos 9773aee
fix formatting
umbynos 3b3d4a4
fix `docs:build` to generate commands before building the actual doc
umbynos 3858418
remove website:check since it does the same as docs:build & rename we…
umbynos a207445
uniform validate-docs to publish-docs
umbynos 901f69c
apply suggestions by @per1234
umbynos 11dbb82
Update Taskfile.yml
umbynos File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| name: publish-docs | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| # Branch to base "dev" website on. Set in build.py also. | ||
| - main | ||
| # release branches have names like 0.8.x, 0.9.x, ... | ||
| - "[0-9]+.[0-9]+.x" | ||
| paths: | ||
| - "docs/**" | ||
| - "docsgen/**" | ||
| - "cli/**" | ||
| - ".github/workflows/publish-docs.ya?ml" | ||
| - "Taskfile.ya?ml" | ||
| - "mkdocs.ya?ml" | ||
| - "poetry.lock" | ||
| - "pyproject.toml" | ||
| - "go.mod" | ||
| - "go.sum" | ||
| # Run on branch or tag creation (will be filtered by the publish-determination job) | ||
| create: | ||
|
|
||
| jobs: | ||
| publish-determination: | ||
| runs-on: ubuntu-latest | ||
| outputs: | ||
| result: ${{ steps.determination.outputs.result }} | ||
| steps: | ||
| - name: Determine if documentation should be published on this workflow run | ||
| id: determination | ||
| run: | | ||
| RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x" | ||
| if [[ "${{ github.event_name }}" == "push" || ( "${{ github.event_name }}" == "create" && "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX ) ]]; then | ||
| RESULT="true" | ||
| else | ||
| RESULT="false" | ||
| fi | ||
|
|
||
| echo "::set-output name=result::$RESULT" | ||
| publish: | ||
| runs-on: ubuntu-latest | ||
| needs: publish-determination | ||
| if: needs.publish-determination.outputs.result == 'true' | ||
|
|
||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v2 | ||
|
|
||
| - name: Install Taskfile | ||
| uses: arduino/setup-task@v1 | ||
| with: | ||
| repo-token: ${{ secrets.GITHUB_TOKEN }} | ||
| version: 3.x | ||
|
|
||
| - name: Setup Go | ||
| uses: actions/setup-go@v2 | ||
| with: | ||
| go-version: "1.16" | ||
|
|
||
| - name: Install Python | ||
| uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: "3.8" | ||
|
|
||
| - name: Install Python dependencies | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| python -m pip install poetry | ||
|
|
||
| - name: Install Python dependencies | ||
| run: poetry install --no-root | ||
|
|
||
| - name: Publish docs | ||
| # 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. | ||
| 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 | ||
| poetry run python docs/build/build.py | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| # Source: | ||
| # https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/build/build.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 sys | ||
| import re | ||
| import subprocess | ||
|
|
||
| import click | ||
| 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 "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("--dry", is_flag=True) | ||
| @click.option("--remote", default="origin", help="The git remote where to push.") | ||
| def main(dry, remote): | ||
| # 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 script (must be run from within the repo tree): | ||
| # $python build.py | ||
| # | ||
| if __name__ == "__main__": | ||
| sys.exit(main()) |
Empty file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| /* | ||
| arduino-fwuploader | ||
| Copyright (c) 2021 Arduino LLC. All right reserved. | ||
| This library is free software; you can redistribute it and/or | ||
| modify it under the terms of the GNU Lesser General Public | ||
| License as published by the Free Software Foundation; either | ||
| version 2.1 of the License, or (at your option) any later version. | ||
| This library is distributed in the hope that it will be useful, | ||
| but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| Lesser General Public License for more details. | ||
| You should have received a copy of the GNU Lesser General Public | ||
| License along with this library; if not, write to the Free Software | ||
| Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA | ||
| */ | ||
|
|
||
| package main | ||
|
|
||
| import ( | ||
| "log" | ||
| "os" | ||
|
|
||
| "github.com/arduino/arduino-fwuploader/cli" | ||
| "github.com/spf13/cobra/doc" | ||
| ) | ||
|
|
||
| func main() { | ||
| if len(os.Args) < 2 { | ||
| log.Fatal("Please provide output folder") | ||
| } | ||
|
|
||
| cli := cli.NewCommand() | ||
| cli.DisableAutoGenTag = true // Disable addition of auto-generated date stamp | ||
| err := doc.GenMarkdownTree(cli, os.Args[1]) | ||
| if err != nil { | ||
| log.Fatal(err) | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.