From 99cd9f4fa64a17041c27ab7271bf38c643ae3b3e Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 28 Jul 2021 20:19:52 -0700 Subject: [PATCH 1/2] Make `docs:check-links` task Windows compatible. `npx --call` uses the native shell. This means the shell code used by the task does not work on Windows. After quite a bit of unsuccessful efforts, I decided that it is simply too difficult to use npx for this application on Windows. So the Windows user is required to have markdown-link-check installed and in PATH. Because Task uses an integrated shell interpreter, shell code is usable as long as it is not wrapped in a `npx --call` command. --- Taskfile.yml | 42 +++++++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 26ce413f9..dbf770a55 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -196,13 +196,41 @@ tasks: desc: Check for dead links in documentation cmds: - | - npx --package markdown-link-check --call ' - STATUS=0 - for file in $(find -name "*.md"); do - markdown-link-check --quiet "$file" - STATUS=$(( $STATUS + $? )) - done - exit $STATUS' + if [[ "{{.OS}}" == "Windows_NT" ]]; then + # npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows, + # so the Windows user is required to have markdown-link-check installed and in PATH. + if ! which markdown-link-check &>/dev/null; then + echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme" + exit 1 + fi + # Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero + # exit status, but it's better to check all links before exiting. + set +o errexit + STATUS=0 + # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows + # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives + # \ characters special treatment on Windows in an attempt to support them as path separators. + for file in $(find . -regex ".*[.]md"); do + markdown-link-check \ + --quiet \ + --config "./.markdown-link-check.json" \ + "$file" + STATUS=$(( $STATUS + $? )) + done + exit $STATUS + else + npx --package=markdown-link-check --call=' + STATUS=0 + for file in $(find . -regex ".*[.]md"); do + markdown-link-check \ + --quiet \ + --config "./.markdown-link-check.json" \ + "$file" + STATUS=$(( $STATUS + $? )) + done + exit $STATUS + ' + fi docs:check-formatting: desc: Check formatting of documentation files From 77e2593bb0910aa57c064104c45715e174eaf518 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 28 Jul 2021 20:28:02 -0700 Subject: [PATCH 2/2] Add CI workflow to check Markdown files for problems On every push and pull request that affects relevant files, and periodically, check the repository's Markdown files for problems: - Use markdownlint to check for common problems and formatting. - Use markdown-link-check to check for broken links. The Arduino tooling Markdown style is defined by the `.markdownlint.yml` file. In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them via a `.markdownlintignore` file: https://github.com/igorshubovych/markdownlint-cli#ignoring-files markdown-link-check is configured via the `.markdown-link-check.json` file: https://github.com/tcort/markdown-link-check#config-file-format This duplicates the link check capability previously provided by the "Check links" workflow, so that has been removed. --- .github/workflows/check-links.yml | 63 ------------- .github/workflows/check-markdown-task.yml | 66 ++++++++++++++ .markdown-link-check.json | 5 ++ .markdownlint.yml | 62 +++++++++++++ README.md | 1 + Taskfile.yml | 104 +++++++++++++--------- 6 files changed, 197 insertions(+), 104 deletions(-) delete mode 100644 .github/workflows/check-links.yml create mode 100644 .github/workflows/check-markdown-task.yml create mode 100644 .markdown-link-check.json create mode 100644 .markdownlint.yml diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml deleted file mode 100644 index ddc3ff0b7..000000000 --- a/.github/workflows/check-links.yml +++ /dev/null @@ -1,63 +0,0 @@ -name: Check documentation links - -on: - push: - paths: - - ".github/workflows/check-links.yml" - - "Taskfile.yml" - - "**.md" - pull_request: - paths: - - ".github/workflows/check-links.yml" - - "Taskfile.yml" - - "**.md" - schedule: - # Run every Tuesday at 03:00 UTC to catch broken links caused by external changes - - cron: "0 3 * * 2" - -jobs: - check-links: - runs-on: ubuntu-latest - - env: - DOCUMENTATION_REQUIREMENTS_PATH: ./docs/requirements_docs.txt - - steps: - - name: Checkout local repository - uses: actions/checkout@v2 - - - name: Install Taskfile - uses: arduino/setup-task@v1 - 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(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 diff --git a/.github/workflows/check-markdown-task.yml b/.github/workflows/check-markdown-task.yml new file mode 100644 index 000000000..1dd9350ae --- /dev/null +++ b/.github/workflows/check-markdown-task.yml @@ -0,0 +1,66 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md +name: Check Markdown + +# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows +on: + push: + paths: + - ".github/workflows/check-markdown-task.ya?ml" + - ".markdown-link-check.json" + - "Taskfile.ya?ml" + - "**/.markdownlint*" + - "**.mdx?" + - "**.mkdn" + - "**.mdown" + - "**.markdown" + pull_request: + paths: + - ".github/workflows/check-markdown-task.ya?ml" + - ".markdown-link-check.json" + - "Taskfile.ya?ml" + - "**/.markdownlint*" + - "**.mdx?" + - "**.mkdn" + - "**.mdown" + - "**.markdown" + schedule: + # Run every Tuesday at 8 AM UTC to catch breakage caused by external changes. + - cron: "0 8 * * TUE" + workflow_dispatch: + repository_dispatch: + +jobs: + lint: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Initialize markdownlint-cli problem matcher + uses: xt0rted/markdownlint-problem-matcher@v1 + + - name: Install Task + uses: arduino/setup-task@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + version: 3.x + + - name: Lint + run: task markdown:lint + + links: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Install Task + uses: arduino/setup-task@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + version: 3.x + + - name: Check links + run: task --silent markdown:check-links diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 000000000..da7987976 --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,5 @@ +{ + "retryOn429": true, + "retryCount": 3, + "aliveStatusCodes": [200, 206] +} diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 000000000..65b6ef7d6 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,62 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlint.yml +# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# The code style defined in this file is the official standardized style to be used in all Arduino projects and should +# not be modified. +# Note: Rules disabled solely because they are redundant to Prettier are marked with a "Prettier" comment. + +default: false +MD001: false +MD002: false +MD003: false # Prettier +MD004: false # Prettier +MD005: false # Prettier +MD006: false # Prettier +MD007: false # Prettier +MD008: false # Prettier +MD009: + br_spaces: 0 + strict: true + list_item_empty_lines: false # Prettier +MD010: false # Prettier +MD011: true +MD012: false # Prettier +MD013: false +MD014: false +MD018: true +MD019: false # Prettier +MD020: true +MD021: false # Prettier +MD022: false # Prettier +MD023: false # Prettier +MD024: false +MD025: + level: 1 + front_matter_title: '^\s*"?title"?\s*[:=]' +MD026: false +MD027: false # Prettier +MD028: false +MD029: + style: one +MD030: + ul_single: 1 + ol_single: 1 + ul_multi: 1 + ol_multi: 1 +MD031: false # Prettier +MD032: false # Prettier +MD033: false +MD034: false +MD035: false # Prettier +MD036: false +MD037: true +MD038: true +MD039: true +MD040: false +MD041: false +MD042: true +MD043: false +MD044: false +MD045: true +MD046: + style: fenced +MD047: false # Prettier diff --git a/README.md b/README.md index 2c3f40798..5cadd73e3 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ [![Tests Status](https://github.com/arduino/arduino-lint/workflows/Run%20tests/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Run+tests) [![Check Go status](https://github.com/arduino/arduino-lint/actions/workflows/check-go-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-go-task.yml) [![Nightly Status](https://github.com/arduino/arduino-lint/workflows/Nightly%20build/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Nightly+build) +[![Check Markdown status](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml) [![Docs Status](https://github.com/arduino/arduino-lint/workflows/Publish%20documentation/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Publish+documentation) [![Codecov](https://codecov.io/gh/arduino/arduino-lint/branch/main/graph/badge.svg?token=nprqPQMbdh)](https://codecov.io/gh/arduino/arduino-lint) [![Check Certificates status](https://github.com/arduino/arduino-lint/actions/workflows/check-certificates.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-certificates.yml) diff --git a/Taskfile.yml b/Taskfile.yml index dbf770a55..4b5970d90 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -110,6 +110,61 @@ tasks: cmds: - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + # 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 + cmds: + - npx markdownlint-cli "**/*.md" + + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:fix: + desc: Automatically correct linting violations in Markdown files where possible + cmds: + - npx markdownlint-cli --fix "**/*.md" + + # 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 + # npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows, + # so the Windows user is required to have markdown-link-check installed and in PATH. + if ! which markdown-link-check &>/dev/null; then + echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme" + exit 1 + fi + # Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero + # exit status, but it's better to check all links before exiting. + set +o errexit + STATUS=0 + # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows + # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives + # \ characters special treatment on Windows in an attempt to support them as path separators. + for file in $(find . -regex ".*[.]md"); do + markdown-link-check \ + --quiet \ + --config "./.markdown-link-check.json" \ + "$file" + STATUS=$(( $STATUS + $? )) + done + exit $STATUS + else + npx --package=markdown-link-check --call=' + STATUS=0 + for file in $(find . -regex ".*[.]md"); do + markdown-link-check \ + --quiet \ + --config "./.markdown-link-check.json" \ + "$file" + STATUS=$(( $STATUS + $? )) + done + exit $STATUS + ' + fi + python:check: cmds: - task: python:lint @@ -126,6 +181,11 @@ tasks: - poetry install --no-root - poetry run black . + docs:generate: + desc: Create all generated documentation content + deps: + - task: docs:gen + docs:gen: desc: Generate command reference dir: ./docsgen @@ -161,7 +221,9 @@ tasks: desc: Lint and check formatting of documentation files cmds: - task: docs:check-formatting - - task: docs:check-links + - task: markdown:lint + - task: markdown:fix + - task: markdown:check-links docs:lint: desc: Lint documentation files @@ -192,46 +254,6 @@ tasks: exit 1 fi - docs:check-links: - desc: Check for dead links in documentation - cmds: - - | - if [[ "{{.OS}}" == "Windows_NT" ]]; then - # npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows, - # so the Windows user is required to have markdown-link-check installed and in PATH. - if ! which markdown-link-check &>/dev/null; then - echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme" - exit 1 - fi - # Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero - # exit status, but it's better to check all links before exiting. - set +o errexit - STATUS=0 - # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows - # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives - # \ characters special treatment on Windows in an attempt to support them as path separators. - for file in $(find . -regex ".*[.]md"); do - markdown-link-check \ - --quiet \ - --config "./.markdown-link-check.json" \ - "$file" - STATUS=$(( $STATUS + $? )) - done - exit $STATUS - else - npx --package=markdown-link-check --call=' - STATUS=0 - for file in $(find . -regex ".*[.]md"); do - markdown-link-check \ - --quiet \ - --config "./.markdown-link-check.json" \ - "$file" - STATUS=$(( $STATUS + $? )) - done - exit $STATUS - ' - fi - docs:check-formatting: desc: Check formatting of documentation files cmds: