diff --git a/.editorconfig b/.editorconfig index 18e97c59..88a69573 100644 --- a/.editorconfig +++ b/.editorconfig @@ -25,7 +25,7 @@ indent_style = space indent_size = 2 indent_style = space -[*.go] +[*.{go,mod}] indent_style = tab [*.java] diff --git a/workflow-templates/assets/check-markdown-task/Taskfile.yml b/workflow-templates/assets/check-markdown-task/Taskfile.yml index cbd40a06..79d556a5 100644 --- a/workflow-templates/assets/check-markdown-task/Taskfile.yml +++ b/workflow-templates/assets/check-markdown-task/Taskfile.yml @@ -2,6 +2,11 @@ version: "3" tasks: + docs:generate: + desc: Create all generated documentation content + # This is an "umbrella" task used to call any documentation generation processes the project has. + # It can be left empty if there are none. + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml markdown:lint: desc: Check for problems in Markdown files @@ -17,6 +22,8 @@ tasks: # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml markdown:check-links: desc: Check for broken links + deps: + - task: docs:generate cmds: - | if [[ "{{.OS}}" == "Windows_NT" ]]; then diff --git a/workflow-templates/assets/check-mkdocs-task/Taskfile.yml b/workflow-templates/assets/check-mkdocs-task/Taskfile.yml index f2a3984c..d83d68ff 100644 --- a/workflow-templates/assets/check-mkdocs-task/Taskfile.yml +++ b/workflow-templates/assets/check-mkdocs-task/Taskfile.yml @@ -2,10 +2,16 @@ version: "3" tasks: + docs:generate: + desc: Create all generated documentation content + # This is an "umbrella" task used to call any documentation generation processes the project has. + # It can be left empty if there are none. + # 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: + - task: docs:generate - task: poetry:install-deps cmds: - poetry run mkdocs build --strict @@ -14,6 +20,7 @@ tasks: website:serve: desc: Run website locally deps: + - task: docs:generate - task: poetry:install-deps cmds: - poetry run mkdocs serve diff --git a/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/.gitkeep b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml new file mode 100644 index 00000000..8ed437a4 --- /dev/null +++ b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml @@ -0,0 +1,23 @@ +version: "3" + +vars: + PROJECT_NAME: TODO + +tasks: + # 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: + - task: go:cli-docs + # 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 + cmds: + # 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 diff --git a/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod new file mode 100644 index 00000000..5f0475e1 --- /dev/null +++ b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod @@ -0,0 +1,12 @@ +// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod +// TODO: replace MODULE_NAME with the project's module name +module MODULE_NAME/docsgen + +go 1.14 + +replace MODULE_NAME => ../ + +require ( + MODULE_NAME v0.0.0 + github.com/spf13/cobra v1.1.1 +) diff --git a/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go new file mode 100644 index 00000000..6e5798ea --- /dev/null +++ b/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go @@ -0,0 +1,38 @@ +// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go +// +// 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. + +// Package main generates Markdown documentation for the project's CLI. +package main + +import ( + "os" + + // TODO: Replace CLI_PACKAGE_NAME with the project's Cobra CLI package name + "CLI_PACKAGE_NAME" + "github.com/spf13/cobra/doc" +) + +func main() { + if len(os.Args) < 2 { + print("error: Please provide the output folder argument") + os.Exit(1) + } + + cli := cli.Root() + cli.DisableAutoGenTag = true // Disable addition of auto-generated date stamp + err := doc.GenMarkdownTree(cli, os.Args[1]) + if err != nil { + panic(err) + } +} diff --git a/workflow-templates/assets/shared/.editorconfig b/workflow-templates/assets/shared/.editorconfig index 18e97c59..88a69573 100644 --- a/workflow-templates/assets/shared/.editorconfig +++ b/workflow-templates/assets/shared/.editorconfig @@ -25,7 +25,7 @@ indent_style = space indent_size = 2 indent_style = space -[*.go] +[*.{go,mod}] indent_style = tab [*.java] diff --git a/workflow-templates/check-markdown-task.md b/workflow-templates/check-markdown-task.md index 2ef187a0..361478c2 100644 --- a/workflow-templates/check-markdown-task.md +++ b/workflow-templates/check-markdown-task.md @@ -28,6 +28,10 @@ The code style defined in `.markdownlint.yml` is the official standardized style ### Configuration +#### Taskfile + +Add any documentation generation processes to the `docs:generate` umbrella task. + #### markdownlint In the event the repository contains externally maintained Markdown files, `markdownlint` can be configured to ignore them via a `.markdownlintignore` file: diff --git a/workflow-templates/check-mkdocs-task.md b/workflow-templates/check-mkdocs-task.md index 4493197e..257a5fd7 100644 --- a/workflow-templates/check-mkdocs-task.md +++ b/workflow-templates/check-mkdocs-task.md @@ -24,6 +24,12 @@ See [the "Deploy Website" (MkDocs, Poetry) workflow documentation](deploy-mkdocs ### Configuration +#### Taskfile + +Add any documentation generation processes to the `docs:generate` umbrella task. + +#### MkDocs + See [the "Deploy Website" (MkDocs, Poetry) workflow documentation](deploy-mkdocs-poetry.md#configuration) ### Readme badge diff --git a/workflow-templates/dependabot/workflow-template-copies/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/workflow-templates/dependabot/workflow-template-copies/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml new file mode 100644 index 00000000..37726cb8 --- /dev/null +++ b/workflow-templates/dependabot/workflow-template-copies/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml @@ -0,0 +1,90 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md +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" + paths: + - "docs/**" + - ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml" + - "go.mod" + - "go.sum" + - "Taskfile.ya?ml" + - "**.go" + - "docsgen/**" + - "mkdocs.ya?ml" + - "poetry.lock" + - "pyproject.toml" + # 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 repository + uses: actions/checkout@v2 + + - name: Install Python + uses: actions/setup-python@v2 + with: + python-version: "3.9" + + - name: Install Poetry + run: | + 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 + + - name: Determine versioning parameters + id: determine-versioning + run: echo "::set-output name=data::$(poetry run python docs/siteversion/siteversion.py)" + + - name: Publish documentation + 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 mike deploy \ + --update-aliases \ + --push \ + --remote origin \ + ${{ fromJson(steps.determine-versioning.outputs.data).version }} \ + ${{ fromJson(steps.determine-versioning.outputs.data).alias }} diff --git a/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md b/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md new file mode 100644 index 00000000..6f9e7046 --- /dev/null +++ b/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md @@ -0,0 +1,151 @@ +# "Deploy Website" workflow (Cobra, versioned, MkDocs, Poetry) + +Generate a command line reference for projects using [the Cobra Go module](https://cobra.dev/) and deploy a versioned [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/). + +This uses Cobra's built-in Markdown documentation generation capability:
+https://github.com/spf13/cobra/blob/master/doc/md_docs.md + +Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important for the reader to be able to access the documentation for the specific version of the project they are using. +The system provides a easy access to a website version for the documentation content at: + +- The tip of the default branch ("dev") +- The latest release ("latest") +- Each minor version series (e.g., "1.2") + +The website version is selectable via a menu on the website as well as the URL of each documentation page. + +## Installation + +### Workflow + +Install the [`deploy-cobra-mkdocs-versioned-poetry.yml`](deploy-cobra-mkdocs-versioned-poetry.yml) GitHub Actions workflow to `.github/workflows/` + +### Assets + +- Base assets - See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#assets) +- [`Taskfile.yml`](assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml) - documentation generation tasks. + - Install to: repository root (or merge into the existing `Taskfile.yml`). +- [`Taskfile.yml`](assets/check-prettier-formatting/Taskfile.yml) - documentation formatting task. + - Merge into `Taskfile.yml` +- [`docsgen`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen) - command line reference generator. + - Install to: `docsgen/` +- [`.gitkeep`](assets/deploy-cobra-mkdocs-versioned-poetry/.gitkeep) - empty placeholder file to preserve the generated documentation's target folder in the repository. + - Install to: `docs/commands/` + +### Dependencies + +See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#dependencies) for the instructions to install the dependencies + +### Configuration + +#### Taskfile + +Set the `PROJECT_NAME` variable to the project name. + +If there are any additional documentation generation tasks, add them to the `docs:generate` umbrella task. + +#### `docsgen` + +- [`go.mod`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod) - replace `MODULE_NAME` with the project's module name. +- [`main.go`](assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go) - replace `CLI_PACKAGE_NAME` with the project's Cobra CLI package name + +Run the following command from the `docsgen/` folder: + +``` +go mod tidy +``` + +Commit the resulting `docsgen/go.sum` file to the repository. + +#### Configure base assets + +See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#configuration). + +#### Define "dev" source branch + +The system is configured for the repository branch used as the source for the "dev" website version having the name `main`. If the project's development branch has another name, then configure it: + +- `on.push.branches[0]` in `deploy-cobra-mkdocs-versioned-poetry.yml` +- `DEV_BRANCHES` in [`siteversion/siteversion.py`](assets/deploy-mkdocs-versioned/siteversion/siteversion.py) + +#### Configure `.gitignore` + +Add the following to `.gitignore`: + +``` +/docsgen/ +/docsgen/.exe +/docs/commands/*.md +``` + +(where "``" is the filename of the application's executable, as defined in the Taskfile `PROJECT_NAME` variable. + +### Setup + +1. Checkout the branch of the repository that contains the documentation source files for the "dev" version of the website (e.g., `main`). +1. Run the following command: + ``` + task docs:generate + ``` +1. Follow the remaining setup steps from the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#setup). + +### Readme badge + +Markdown badge: + +```markdown +[![Deploy Website status](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/REPO_OWNER/REPO_NAME/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml) +``` + +Replace the `REPO_OWNER` and `REPO_NAME` placeholders in the URLs with the final repository owner and name ([example](https://raw.githubusercontent.com/arduino-libraries/ArduinoIoTCloud/master/README.md)). + +--- + +Asciidoc badge: + +```adoc +image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg["Deploy Website status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml"] +``` + +Define the `{repository-owner}` and `{repository-name}` attributes and use them throughout the readme ([example](https://raw.githubusercontent.com/arduino-libraries/WiFiNINA/master/README.adoc)). + +## Website versioning + +See the ["Deploy Website" workflow (versioned, MkDocs, Poetry) documentation](deploy-mkdocs-versioned-poetry.md#website-versioning) for an explanation of how the versioning works. + +## Commit message + +``` +Add CI workflow to deploy a versioned MkDocs-based website to GitHub Pages + +On every push to the repository's default branch or release branch, generate a command line reference and deploy the +repository's MkDocs-based static website to GitHub Pages. + +Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important +for the reader to be able to access the documentation for the specific version of the project they are using. + +The documentation system provides access to: + +- The tip of the default branch ("dev") +- The latest release ("latest") +- Each minor version series (e.g., "1.2") + +The website version is selectable via a menu on the website as well as the URL of each documentation page. +``` + +## PR message + +```markdown +On every push to the repository's default branch, generate a command line reference and deploy the repository's [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/). + +Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important +for the reader to be able to access the documentation for the specific version of the project they are using. + +With the help of [mike](https://github.com/jimporter/mike), the documentation system provides access to: + +- The tip of the default branch ("dev") +- The latest release ("latest") +- Each minor version series (e.g., "1.2") + +The website version is selectable via a menu on the website as well as the URL of each documentation page. +``` diff --git a/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.yml b/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.yml new file mode 100644 index 00000000..37726cb8 --- /dev/null +++ b/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.yml @@ -0,0 +1,90 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md +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" + paths: + - "docs/**" + - ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml" + - "go.mod" + - "go.sum" + - "Taskfile.ya?ml" + - "**.go" + - "docsgen/**" + - "mkdocs.ya?ml" + - "poetry.lock" + - "pyproject.toml" + # 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 repository + uses: actions/checkout@v2 + + - name: Install Python + uses: actions/setup-python@v2 + with: + python-version: "3.9" + + - name: Install Poetry + run: | + 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 + + - name: Determine versioning parameters + id: determine-versioning + run: echo "::set-output name=data::$(poetry run python docs/siteversion/siteversion.py)" + + - name: Publish documentation + 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 mike deploy \ + --update-aliases \ + --push \ + --remote origin \ + ${{ fromJson(steps.determine-versioning.outputs.data).version }} \ + ${{ fromJson(steps.determine-versioning.outputs.data).alias }}