Merge pull request docker#15268 from jedevc/linting-annotations

Add GitHub Actions annotations for linting

.github/workflows/build.yml

@@ -45,9 +45,56 @@ jobs:
         name: Validate
         uses: docker/bake-action@v2
         with:
-          targets: ${{ matrix.target }}
+          targets: ${{ matrix.target }}-output
           set: |
+            *.cache-to=type=gha,scope=validate-${{ matrix.target }},mode=max
+            *.cache-from=type=gha,scope=validate-${{ matrix.target }}
             *.cache-from=type=gha,scope=build
+      -
+        name: Annotate
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const fs = require('fs');
+            const results = fs.readFileSync('lint/results', 'utf-8');
+            if (results.length == 0) {
+              process.exit(0);
+            }
+
+            // print results
+            console.log(results);
+            process.exitCode = 1;
+
+            // construct annotations by parsing output
+            switch ("${{ matrix.target }}") {
+            case "htmlproofer":
+              const re = /^- (.+)\n  \*  (.+) \(line (\d+)\)\n(.+)$/gm;
+              while (true) {
+                const result = re.exec(results);
+                if (result === null) {
+                  break;
+                }
+
+                core.error(`${result[2]}\n${result[4]}`, {
+                  title: 'Link check failed',
+                  // file: result[1],
+                  // startLine: result[3],
+                });
+              }
+              break;
+            case "mdl":
+              const jsonResults = JSON.parse(results);
+              for (const result of jsonResults) {
+                const title = result.rule + (result.aliases.length > 0 ? ` (${result.aliases[0]})` : ``);
+                console.log(`${result.filename}:${result.line}; ${title} - ${result.description}`);
+                core.error(result.description, {
+                  title: title,
+                  file: result.filename,
+                  startLine: result.line,
+                });
+              }
+              break;
+            }
 
   # build-releaser job will just build _releaser app used for Netlify and
   # AWS deployment in publish workflow. it's just to be sure it builds correctly.

.gitignore

@@ -9,3 +9,4 @@ _site/**
 CNAME
 _kbase/**
 /vendor
+/lint

.markdownlint.json

@@ -0,0 +1,13 @@
+{
+  "default": false,
+  "hr-style": true,
+  "no-missing-space-atx": true,
+  "no-multiple-space-atx": true,
+  "no-missing-space-closed-atx": true,
+  "no-multiple-space-closed-atx": true,
+  "no-space-in-emphasis": true,
+  "no-space-in-code": true,
+  "no-space-in-links": true,
+  "ol-prefix": {"style": "ordered"},
+  "no-reversed-links": true
+}

.mdlrc.style.rb → .markdownlint.rb

@@ -1,4 +1,7 @@
 # https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+#
+# When updating rules in this file, ensure the corresponding rule list in
+# .markdownlint.json is also updated.
 
 # style
 rule 'header-style'

CONTRIBUTING.md

@@ -6,8 +6,8 @@ as possible for you to work in this repository. The documentation for Docker is
 ## Table of Contents
 
 - [Contribution guidelines](#contribution-guidelines)
-  - [Files not edited here](#files-not-edited-here)
   - [Important files](#important-files)
+  - [Files not edited here](#files-not-edited-here)
   - [Per-page front-matter](#per-page-front-matter)
 - [Pull request guidelines](#pull-request-guidelines)
 - [Collaborate on a pull request](#collaborate-on-a-pull-request)
@@ -192,7 +192,18 @@ repository. Compressing images after adding them to the repository actually wors
 
 ### Style guide
 
-Docker does not currently maintain a style guide. Follow the examples set by the existing documentation and use your best judgment.
+Docker does not currently maintain a style guide. Follow the examples set by
+the existing documentation and use your best judgment.
+
+We use [markdownlint](https://github.com/markdownlint/markdownlint) to ensure
+consistent markdown source, and to catch potential formatting issues as early
+as possible. While CI/CD will catch these during the PR review process, you may
+wish to configure your IDE to catch these while writing.
+
+For VSCode, you can use the [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+plugin, which will automatically detect and apply the pre-made rules in
+`.markdownlint.json`. This plugin also comes with auto-fix functionality, see
+the plugin documentation for more information.
 
 ## Build and preview the docs locally
 

Dockerfile

@@ -55,23 +55,52 @@ RUN --mount=type=bind,target=.,rw \
 EOT
 
 # htmlproofer checks for broken links
-FROM gem AS htmlproofer
-RUN --mount=type=bind,from=generate,source=/out,target=_site \
+FROM gem AS htmlproofer-base
+RUN --mount=type=bind,from=generate,source=/out,target=_site <<EOF
   htmlproofer ./_site \
     --disable-external \
     --internal-domains="docs.docker.com,docs-stage.docker.com,localhost:4000" \
     --file-ignore="/^./_site/engine/api/.*$/,./_site/registry/configuration/index.html" \
-    --url-ignore="/^/docker-hub/api/latest/.*$/,/^/engine/api/v.+/#.*$/,/^/glossary/.*$/"
+    --url-ignore="/^/docker-hub/api/latest/.*$/,/^/engine/api/v.+/#.*$/,/^/glossary/.*$/" > /results 2>&1
+  rc=$?
+  if [[ $rc -eq 0 ]]; then
+    echo -n > /results
+  fi
+EOF
+
+FROM htmlproofer-base as htmlproofer
+RUN <<EOF
+  cat /results
+  [ ! -s /results ] || exit 1
+EOF
+
+FROM scratch as htmlproofer-output
+COPY --from=htmlproofer-base /results /results
 
 # mdl is a lint tool for markdown files
-FROM gem AS mdl
+FROM gem AS mdl-base
+ARG MDL_JSON
 ARG MDL_STYLE
-RUN --mount=type=bind,target=. \
-  mdl --ignore-front-matter --style=${MDL_STYLE:-'.mdlrc.style.rb'} $( \
+RUN --mount=type=bind,target=. <<EOF
+  mdl --ignore-front-matter ${MDL_JSON:+'--json'} --style=${MDL_STYLE:-'.markdownlint.rb'} $( \
     find '.' -name '*.md' \
       -not -path './registry/*' \
       -not -path './desktop/extensions-sdk/*' \
-  )
+  ) > /results
+  rc=$?
+  if [[ $rc -eq 0 ]]; then
+    echo -n > /results
+  fi
+EOF
+
+FROM mdl-base as mdl
+RUN <<EOF
+  cat /results
+  [ ! -s /results ] || exit 1
+EOF
+
+FROM scratch as mdl-output
+COPY --from=mdl-base /results /results
 
 # Release the generated files in a scratch image
 # Can be output to your host with:

docker-bake.hcl

@@ -41,12 +41,27 @@ target "htmlproofer" {
   output = ["type=cacheonly"]
 }
 
+target "htmlproofer-output" {
+  inherits = ["_common"]
+  target = "htmlproofer-output"
+  output = ["./lint"]
+}
+
 target "mdl" {
   inherits = ["_common"]
   target = "mdl"
   output = ["type=cacheonly"]
 }
 
+target "mdl-output" {
+  inherits = ["_common"]
+  target = "mdl-output"
+  output = ["./lint"]
+  args = {
+    MDL_JSON = 1
+  }
+}
+
 #
 # releaser targets are defined in _releaser/Dockerfile
 # and are used for Netlify and AWS S3 deployment