Add a markdownlint job and role

This tool will ensure that your markdown files follow some best
practices.

Change-Id: I7bcc70443dbe5fa31e3cc1139d608834c00851b9

doc/source/general-jobs.rst

@@ -3,6 +3,7 @@ General Purpose Jobs
 
 .. zuul:autojob:: dco-license
 .. zuul:autojob:: unittests
+.. zuul:autojob:: markdownlint
 .. zuul:autojob:: multinode
 .. zuul:autojob:: run-test-command
 .. zuul:autojob:: upload-git-mirror

doc/source/general-roles.rst

@@ -15,8 +15,11 @@ General Purpose Roles
 .. zuul:autorole:: emit-job-header
 .. zuul:autorole:: enable-netconsole
 .. zuul:autorole:: ensure-dstat-graph
+.. zuul:autorole:: ensure-markdownlint
+.. zuul:autorole:: fetch-markdownlint
 .. zuul:autorole:: git-prepare-nodecache
 .. zuul:autorole:: log-inventory
+.. zuul:autorole:: markdownlint
 .. zuul:autorole:: mirror-workspace-git-repos
 .. zuul:autorole:: multi-node-bridge
 .. zuul:autorole:: multi-node-firewall

playbooks/markdownlint/post.yaml

@@ -0,0 +1,4 @@
+- name: Get markdownlint report
+  hosts: all
+  roles:
+    - fetch-markdownlint

playbooks/markdownlint/pre.yaml

@@ -0,0 +1,5 @@
+- name: Ensure Markdownlint is installed via NPM
+  hosts: all
+  roles:
+    - install-nodejs
+    - ensure-markdownlint

playbooks/markdownlint/run.yaml

@@ -0,0 +1,5 @@
+- name: Run markdownlint
+  hosts: all
+  roles:
+    - revoke-sudo
+    - markdownlint

roles/ensure-markdownlint/README.rst

@@ -0,0 +1 @@
+Ensure markdownlint-cli from NPM is installed.

roles/ensure-markdownlint/tasks/main.yaml

@@ -0,0 +1,4 @@
+- name: Install markdownlint-cli
+  npm:
+    name: markdownlint-cli
+    path: ~/.markdownlint

roles/fetch-markdownlint/README.rst

@@ -0,0 +1,9 @@
+Collect output from a markdownlint run. Assumes you will only run one repo, and
+one node.
+
+**Role Variables**
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   The location of the main working directory of the job.

roles/fetch-markdownlint/defaults/main.yaml

@@ -0,0 +1 @@
+zuul_work_dir: "{{ zuul.project.src_dir }}"

roles/fetch-markdownlint/tasks/main.yaml

@@ -0,0 +1,12 @@
+- name: Is there a markdownlint.txt
+  register: stat_mdl_txt
+  stat:
+    path: "{{ zuul_work_dir }}/markdownlint.txt"
+
+- name: Store on executor
+  when: stat_mdl_txt.stat.exists
+  synchronize:
+    mode: pull
+    src: "{{ zuul_work_dir }}/markdownlint.txt"
+    dest: "{{ zuul.executor.log_root }}/markdownlint.txt"
+    verify_host: true

roles/markdownlint/README.rst

@@ -0,0 +1,8 @@
+Run markdownlint against all markdown files in the given project.
+
+**Role Variables**
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: {{ zuul.project.src_dir }}
+
+   Directory to search for markdown files in.

roles/markdownlint/defaults/main.yaml

@@ -0,0 +1 @@
+zuul_work_dir: "{{ zuul.project.src_dir }}"

roles/markdownlint/tasks/main.yaml

@@ -0,0 +1,16 @@
+- name: find all .md files
+  find:
+    paths: "{{ zuul_work_dir }}"
+    pattern: "*.md"
+  register: markdown_find
+
+- name: Run markdownlint
+  shell: |
+    set -o pipefail
+    set -e
+    ~/.markdownlint/node_modules/.bin/markdownlint {{ item|relpath(zuul_work_dir) }} 2>&1 | tee -a markdownlint.txt
+  args:
+    chdir: "{{ zuul_work_dir }}"
+    executable: /bin/bash
+  with_items: "{{ markdown_find.files|map(attribute='path')|list }}"
+  changed_when: false

zuul.d/python-jobs.yaml

@@ -335,3 +335,14 @@
       - test-requirements.txt
       - tox.ini
 
+- job:
+    name: markdownlint
+    files: '^.*\.md$'
+    pre-run: playbooks/markdownlint/pre.yaml
+    run: playbooks/markdownlint/run.yaml
+    post-run: playbooks/markdownlint/post.yaml
+    description: |
+      Check any markdown for basic lint problems. Include a file named
+      `.markdownlint.json` that is configured according to
+      https://github.com/DavidAnson/markdownlint#optionsconfig
+      to control rule specifics.