Merge pull request #88 from per1234/mkdocs-cli

Add template workflow to generate Cobra docs and deploy a versioned MkDocs-based website to GitHub Pages

Author: per1234

.editorconfig

@@ -25,7 +25,7 @@ indent_style = space
 indent_size = 2
 indent_style = space
 
-[*.go]
+[*.{go,mod}]
 indent_style = tab
 
 [*.java]

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

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

workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/.gitkeep

@@ -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

workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml

@@ -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
+)

workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/go.mod

@@ -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 [email protected].
+
+// 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)
+	}
+}

workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/docsgen/main.go

@@ -25,7 +25,7 @@ indent_style = space
 indent_size = 2
 indent_style = space
 
-[*.go]
+[*.{go,mod}]
 indent_style = tab
 
 [*.java]

workflow-templates/assets/shared/.editorconfig

@@ -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:

workflow-templates/check-markdown-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

workflow-templates/check-mkdocs-task.md

@@ -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 "[email protected]"
+          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 }}