Add documentation website

.github/workflows/check-links.yml

@@ -18,6 +18,10 @@ on:
 jobs:
   check-links:
     runs-on: ubuntu-latest
+
+    env:
+      DOCUMENTATION_REQUIREMENTS_PATH: ./docs/requirements_docs.txt
+
     steps:
       - name: Checkout local repository
         uses: actions/checkout@v2
@@ -28,5 +32,32 @@ jobs:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           version: 3.x
 
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: "1.14"
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles(env.DOCUMENTATION_REQUIREMENTS_PATH) }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Poetry
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+
+      - name: Build documentation website
+        # Ensure the documentation can build. These docs won't be published.
+        run: task docs:build
+
       - name: Check links
         run: task --silent docs:check-links

.github/workflows/publish-docs.yml

@@ -0,0 +1,83 @@
+name: Publish documentation
+
+on:
+  push:
+    branches:
+      - 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.yml"
+  # 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 local repository
+        uses: actions/checkout@v2
+
+      - name: Install Taskfile
+        uses: arduino/actions/setup-taskfile@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: "1.14"
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Poetry
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+
+      - name: Install Python dependencies
+        run: poetry install --no-root
+
+      - name: Publish documentation
+        # 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 "[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 python docs/build.py

.github/workflows/validate-docs.yml

@@ -0,0 +1,61 @@
+name: Validate documentation
+
+on:
+  pull_request:
+    paths:
+      # existing docs
+      - "docs/**"
+      # changes to the cli reference generator
+      - "docsgen/**"
+      # potential changes to commands documentation
+      - "cli/**"
+      # changes to the workflow itself
+      - ".github/workflows/validate-docs.yml"
+  push:
+    paths:
+      - "docs/**"
+      - "docsgen/**"
+      - "cli/**"
+      - "rpc/**"
+      - ".github/workflows/validate-docs.yml"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout local repository
+        uses: actions/checkout@v2
+
+      - name: Install Taskfile
+        uses: arduino/actions/setup-taskfile@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: "1.14"
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Poetry
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+
+      - name: Build documentation website
+        # Ensure the documentation can build. These docs won't be published.
+        run: task docs:build

.gitignore

@@ -12,3 +12,9 @@ coverage_unit.txt
 *.bak
 *.code-workspace
 *.sublime-workspace
+
+# MkDocs
+/site/
+/docsgen/arduino-cli
+/docsgen/arduino-cli.exe
+/docs/commands/*.md

README.md

@@ -6,15 +6,4 @@
 - Sketches
 - Libraries
 
-## Usage
-
-After installing `arduino-lint`, run the command `arduino-lint --help` for usage documentation.
-
-A few additional configuration options only of use for internal/development use of the tool can be set via environment
-variables:
-
-- `ARDUINO_LINT_OFFICIAL` - Set to `"true"` to run the checks that only apply to official Arduino projects.
-- `ARDUINO_LINT_LOG_LEVEL` - Messages with this level and above will be logged.
-  - Supported values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`
-- `ARDUINO_LINT_LOG_FORMAT` - The output format for the logs.
-  - Supported values: `text`, `json`
+For usage instructions, see [the documentation](https://arduino.github.io/arduino-lint/latest/)

Taskfile.yml

@@ -115,6 +115,37 @@ tasks:
       - poetry install --no-root
       - poetry run black .
 
+  docs:gen:
+    desc: Generate command reference
+    dir: ./docsgen
+    cmds:
+      # docs will generate examples using os.Args[0] so we need to call
+      # the generator `arduino-lint`
+      - go build -o arduino-lint{{exeExt}}
+      # we invoke `arduino-lint` like this instead of `./arduino-lint` to remove
+      # the `./` chars from the examples
+      - PATH=. arduino-lint ../docs/commands
+      - task: docs:format
+
+  docs:build:
+    desc: Build documentation website contents
+    cmds:
+      - task: docs:gen
+      - poetry install --no-root
+      - poetry run mkdocs build --strict
+
+  docs:publish:
+    desc: Use Mike to build and push versioned docs
+    cmds:
+      - task: docs:gen
+      - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}}
+
+  docs:serve:
+    desc: Run documentation website locally
+    cmds:
+      - task: docs:build
+      - poetry run mkdocs serve
+
   docs:check:
     desc: Lint and check formatting of documentation files
     cmds:
@@ -229,9 +260,13 @@ vars:
 
   GOLINTFLAGS: "-min_confidence 0.8 -set_exit_status"
 
+  DOCS_VERSION: dev
+  DOCS_ALIAS: ""
+  DOCS_REMOTE: "origin"
+
   PRETTIER: [email protected]
 
   WORKFLOW_SCHEMA_PATH: "$(mktemp -t gha-workflow-schema-XXXXXXXXXX.json)"
 
-  CODESPELL_SKIP_OPTION: '--skip "./.git,./go.mod,./go.sum,./arduino-lint,./arduino-lint.exe,./check/checkfunctions/testdata/libraries/MisspelledSentenceParagraphValue/library.properties"'
+  CODESPELL_SKIP_OPTION: '--skip "./.git,go.mod,go.sum,./arduino-lint,./arduino-lint.exe,./check/checkfunctions/testdata/libraries/MisspelledSentenceParagraphValue/library.properties,./site"'
   CODESPELL_IGNORE_WORDS_OPTION: "--ignore-words ./etc/codespell-ignore-words-list.txt"