Merge branch 'move-markdownlint-to-lint-doc' into 'master'

Move linter invocations from CI job config to lint-doc.sh script

See merge request gitlab-org/gitlab!26379

.gitlab/ci/docs.gitlab-ci.yml

@@ -50,10 +50,6 @@ docs lint:
   needs: []
   script:
     - scripts/lint-doc.sh
-    # Lint Markdown
-    - markdownlint --config .markdownlint.json 'doc/**/*.md'
-    # Lint content (error-level text-scoped rules only)
-    - vale --minAlertLevel error --ignore-syntax doc
     # Prepare docs for build
     - mv doc/ /tmp/gitlab-docs/content/$DOCS_GITLAB_REPO_SUFFIX
     - cd /tmp/gitlab-docs

doc/development/documentation/index.md

@@ -393,15 +393,14 @@ merge request with new or changed docs is submitted, are:
 - [`docs lint`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L48):
   Runs several tests on the content of the docs themselves:
   - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh)
-    checks that:
+    runs the following checks and linters:
     - All cURL examples use the long flags (ex: `--header`, not `-H`).
     - The `CHANGELOG.md` does not contain duplicate versions.
     - No files in `doc/` are executable.
     - No new `README.md` was added.
     - [markdownlint](#markdownlint).
-  - Nanoc tests, which you can [run locally](#previewing-the-changes-live) before
-    pushing to GitLab by executing the command `bundle exec nanoc check internal_links`
-    (or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory:
+    - [Vale](#vale).
+  - Nanoc tests:
     - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L67)
       checks that all internal links (ex: `[link](../index.md)`) are valid.
     - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L69)
@@ -410,6 +409,60 @@ merge request with new or changed docs is submitted, are:
 - If any code or the `doc/README.md` file is changed, a full pipeline will run, which
   runs tests for [`/help`](#gitlab-help-tests).
 
+### Running tests & lint checks locally
+
+Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks
+and Nanoc tests locally.
+
+#### Nanoc tests
+
+To execute Nanoc tests locally:
+
+1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory.
+1. Run:
+
+   ```shell
+   # Check for broken internal links
+   bundle exec nanoc check internal_links
+
+   # Check for broken external links (might take a lot of time to complete).
+   # This test is set to be allowed to fail and is run only in the gitlab-docs project CI
+   bundle exec nanoc check internal_anchors
+   ```
+
+#### Lint checks
+
+Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh)
+script and can be executed as follows:
+
+1. Navigate to the `gitlab` directory.
+1. Run:
+
+   ```shell
+   MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh
+   ```
+
+Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for.
+If you omit it completely, it will default to the `doc/` directory.
+The output should be similar to:
+
+```
+=> Linting documents at path /path/to/gitlab as <user>...
+=> Checking for cURL short options...
+=> Checking for CHANGELOG.md duplicate entries...
+=> Checking /path/to/gitlab/doc for executable permissions...
+=> Checking for new README.md files...
+=> Linting markdown style...
+=> Linting prose...
+✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
+✔ Linting passed
+```
+
+Note that this requires you to either have the required lint tools installed on your machine,
+or a working Docker installation, in which case an image with these tools pre-installed will be used.
+
+For more information on available linters refer to the [linting](#linting) section.
+
 ### Linting
 
 To help adhere to the [documentation style guidelines](styleguide.md), and improve the content

scripts/lint-doc.sh

@@ -48,5 +48,39 @@ then
   exit 1
 fi
 
+MD_DOC_PATH=${MD_DOC_PATH:-doc/**/*.md}
+
+function run_locally_or_in_docker() {
+  local cmd=$1
+  local args=$2
+
+  if hash ${cmd} 2>/dev/null
+  then
+    $cmd $args
+  elif hash docker 2>/dev/null
+  then
+    docker run -t -v ${PWD}:/gitlab -w /gitlab --rm registry.gitlab.com/gitlab-org/gitlab-docs:lint ${cmd} ${args}
+  else
+    echo
+    echo "  ✖ ERROR: '${cmd}' not found. Install '${cmd}' or Docker to proceed." >&2
+    echo
+    exit 1
+  fi
+
+  if [ $? -ne 0 ]
+  then
+    echo
+    echo "  ✖ ERROR: '${cmd}' failed with errors." >&2
+    echo
+    exit 1
+  fi
+}
+
+echo '=> Linting markdown style...'
+run_locally_or_in_docker 'markdownlint' "--config .markdownlint.json ${MD_DOC_PATH}"
+
+echo '=> Linting prose...'
+run_locally_or_in_docker 'vale' "--minAlertLevel error --ignore-syntax ${MD_DOC_PATH}"
+
 echo "✔ Linting passed"
 exit 0