Merge pull request #451 from marquiz/devel/mdlint

docs: enable markdown linting

Makefile

@@ -9,6 +9,8 @@ IMAGE_BUILD_EXTRA_OPTS ?=
 IMAGE_PUSH_CMD ?= docker push
 CONTAINER_RUN_CMD ?= docker run
 
+MDL ?= mdl
+
 # Docker base command for working with html documentation.
 # Use host networking because 'jekyll serve' is stupid enough to use the
 # same site url than the "host" it binds to. Thus, all the links will be
@@ -117,6 +119,9 @@ gofmt-verify:
 ci-lint:
 	golangci-lint run --timeout 5m0s
 
+mdlint:
+	find docs/ -path docs/vendor -prune -false -o -name '*.md' | xargs $(MDL) -s docs/mdl-style.rb
+
 test:
 	$(GO_CMD) test ./cmd/... ./pkg/...
 

docs/advanced/architecture.md

@@ -6,9 +6,11 @@ published: false
 ---
 
 # Architecture
+
 {: .no_toc }
 
 ## Table of contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -16,6 +18,6 @@ published: false
 
 ---
 
-***WORK IN PROGRESS***
+***WORK IN PROGRESS.***
 
 This page first gives an architectural overview and describes principles behind.

docs/advanced/customization-guide.md

@@ -6,9 +6,11 @@ published: false
 ---
 
 # Customization Guide
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -16,7 +18,7 @@ published: false
 
 ---
 
-***WORK IN PROGRESS***
+***WORK IN PROGRESS.***
 
 This document explains with examples how to use hooks, feature files and the
 custom feature source.

docs/advanced/developer-guide.md

@@ -5,9 +5,11 @@ sort: 1
 ---
 
 # Developer Guide
+
 {: .no_toc }
 
 ## Table of contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -36,6 +38,7 @@ make
 ```
 
 #### Push the container image
+
 Optional, this example with Docker.
 
 ```bash
@@ -117,10 +120,13 @@ make IMAGE_REGISTRY=<my custom registry uri>
 Or to specify a build tool different from Docker, It can be done in 2 ways:
 
 1. via environment
+
     ```bash
     IMAGE_BUILD_CMD="buildah bud" make
     ```
+
 1. by overriding the variable value
+
     ```bash
     make  IMAGE_BUILD_CMD="buildah bud"
     ```

docs/advanced/e2e-configuration-reference.md

@@ -6,9 +6,11 @@ published: false
 ---
 
 # End-to-End Test Configuration File Reference
+
 {: .no_toc }
 
 ## Table of contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -16,6 +18,6 @@ published: false
 
 ---
 
-***WORK IN PROGRESS***
+***WORK IN PROGRESS.***
 
 This section describes the end-to-end test configuration file.

docs/advanced/master-commandline-reference.md

@@ -5,9 +5,11 @@ sort: 2
 ---
 
 # NFD-Master Commandline Flags
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC

docs/advanced/worker-commandline-reference.md

@@ -5,9 +5,11 @@ sort: 3
 ---
 
 # NFD-Worker Commandline Flags
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC

docs/advanced/worker-configuration-reference.md

@@ -5,12 +5,14 @@ sort: 4
 ---
 
 # NFD-Worker Configuration File Reference
+
 {: .no_toc }
 
 ## Table of contents
+
 {: .no_toc .text-delta }
 
-***WORK IN PROGRESS***
+***WORK IN PROGRESS.***
 
 1. TOC
 {:toc}

docs/get-started/deployment-and-usage.md

@@ -5,9 +5,11 @@ sort: 3
 ---
 
 # Deployment and Usage
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -36,10 +38,13 @@ is recommended to be done via
    [latest release](https://github.com/operator-framework/operator-lifecycle-manager/releases/latest)
    for detailed instructions.
 1. Install the operator:
+
     ```bash
     kubectl create -f https://operatorhub.io/install/nfd-operator.yaml
     ```
+
 1. Create NodeFeatureDiscovery resource (in `nfd` namespace here):
+
     ```bash
     cat << EOF | kubectl apply -f -
     apiVersion: v1
@@ -107,7 +112,7 @@ Node Feature Discovery Helm chart allow to easily deploy and manage NFD.
 
 [Helm package manager](https://helm.sh/) should be installed.
 
-#### Deployment with Helm
+#### Deployment
 
 To install the chart with the release name node-feature-discovery:
 
@@ -118,8 +123,9 @@ export NFD_NS=node-feature-discovery
 helm install node-feature-discovery ./node-feature-discovery/ --namespace $NFD_NS --create-namespace
 ```
 
-The command deploys Node Feature Discovery on the Kubernetes cluster in the default configuration.
-The Configuration section describes how it can be configured during installation.
+The command deploys Node Feature Discovery on the Kubernetes cluster in the
+default configuration.  The Configuration section describes how it can be
+configured during installation.
 
 #### Configuration
 
@@ -146,7 +152,8 @@ export NFD_NS=node-feature-discovery
 helm uninstall node-feature-discovery --namespace $NFD_NS
 ```
 
-The command removes all the Kubernetes components associated with the chart and deletes the release.
+The command removes all the Kubernetes components associated with the chart and
+deletes the release.
 
 #### Chart Parameters
 
@@ -167,7 +174,6 @@ We have introduced the following Chart parameters.
 | `nameOverride` | string |  | Override the name of the chart |
 | `fullnameOverride` | string |  | Override a default fully qualified app name |
 
-
 ##### Master pod parameters
 
 | `master.*` | dict |  | NFD master deployment configuration |
@@ -194,7 +200,6 @@ We have introduced the following Chart parameters.
 | `worker.tolerations` | dict | {} | NFD worker pod [node tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) |
 | `worker.annotations` | dict | {} | NFD worker pod [metadata](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) |
 
-
 ### Build Your Own
 
 If you want to use the latest development version (master branch) you need to
@@ -258,7 +263,7 @@ nfd-master args, in which case nfd-master verifies that the NodeName presented
 by nfd-worker matches the Common Name (CN) of its certificate. This means that
 each nfd-worker requires a individual node-specific TLS certificate.
 
-## Configuration
+## Worker Configuration
 
 NFD-Worker supports dynamic configuration through a configuration file. The
 default location is `/etc/kubernetes/node-feature-discovery/nfd-worker.conf`,
@@ -274,7 +279,7 @@ re-configurability.
 The provided nfd-worker deployment templates create an empty configmap and
 mount it inside the nfd-worker containers. Configuration can be edited with:
 
-```
+```bash
 kubectl -n ${NFD_NS} edit configmap nfd-worker-conf
 ```
 
@@ -290,7 +295,7 @@ Configuration options can also be specified via the `-options` command line
 flag, in which case no mounts need to be used. The same format as in the config
 file must be used, i.e. JSON (or YAML). For example:
 
-```
+```bash
 -options='{"sources": { "pci": { "deviceClassWhitelist": ["12"] } } }'
 ```
 

docs/get-started/examples-and-demos.md

@@ -5,9 +5,11 @@ sort: 5
 ---
 
 # Examples And Demos
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC

docs/get-started/features.md

@@ -5,9 +5,11 @@ sort: 4
 ---
 
 # Feature Discovery
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -33,7 +35,7 @@ The published node labels encode a few pieces of information:
 
 Feature label names adhere to the following pattern:
 
-```
+```plaintext
 <namespace>/<source name>-<feature name>[.<attribute name>]
 ```
 
@@ -147,7 +149,7 @@ ConfigMap, mounted into the `custom.d` directory.
 
 #### General Nomenclature & Definitions
 
-```
+```plaintext
 Rule        :Represents a matching logic that is used to match on a feature.
 Rule Input  :The input a Rule is provided. This determines how a Rule performs the match operation.
 Matcher     :A composition of Rules, each Matcher may be composed of at most one instance of each Rule.
@@ -190,7 +192,7 @@ between Rules of a given Matcher.
 
 ###### Nomenclature
 
-```
+```plaintext
 Attribute   :A PCI attribute.
 Element     :An identifier of the PCI attribute.
 ```
@@ -217,7 +219,7 @@ partake in the matching process.
 
 ###### Nomenclature
 
-```
+```plaintext
 Attribute   :A USB attribute.
 Element     :An identifier of the USB attribute.
 ```
@@ -244,7 +246,7 @@ partake in the matching process.
 
 ###### Nomenclature
 
-```
+```plaintext
 Element     :A kernel module
 ```
 
@@ -265,7 +267,7 @@ system.
 
 ###### Nomenclature
 
-```
+```plaintext
 Element     :A CPUID flag
 ```
 
@@ -286,7 +288,7 @@ the system.
 
 ###### Nomenclature
 
-```
+```plaintext
 Element     :A Kconfig option
 ```
 
@@ -307,7 +309,7 @@ Rule will match if all provided Elements (kernel config options) are enabled
 
 ###### Nomenclature
 
-```
+```plaintext
 Element     :A nodename regexp pattern
 ```
 
@@ -426,7 +428,7 @@ The **kernel** feature source supports the following labels:
 
 | Feature | Attribute           | Description                                  |
 | ------- | ------------------- | -------------------------------------------- |
-| config  | &lt;option name&gt; | Kernel config option is enabled (set 'y' or 'm').<br> Default options are `NO_HZ`, `NO_HZ_IDLE`, `NO_HZ_FULL` and `PREEMPT`
+| config  | &lt;option name&gt; | Kernel config option is enabled (set 'y' or 'm'). Default options are `NO_HZ`, `NO_HZ_IDLE`, `NO_HZ_FULL` and `PREEMPT`
 | selinux | enabled             | Selinux is enabled on the node
 | version | full                | Full kernel version as reported by `/proc/sys/kernel/osrelease` (e.g. '4.5.6-7-g123abcde')
 |         | major               | First component of the kernel version (e.g. '4')
@@ -471,7 +473,7 @@ of fields used in `<device label>` is configurable, valid fields being `class`,
 `vendor`, `device`, `subsystem_vendor` and `subsystem_device`.  Defaults are
 `class` and `vendor`. An example label using the default label fields:
 
-```
+```plaintext
 feature.node.kubernetes.io/pci-1200_8086.present=true
 ```
 
@@ -492,7 +494,7 @@ of fields used in `<device label>` is configurable, valid fields being `class`,
 `vendor`, and `device`.  Defaults are `class`, `vendor` and `device`. An
 example label using the default label fields:
 
-```
+```plaintext
 feature.node.kubernetes.io/usb-fe_1a6e_089a.present=true
 ```
 
@@ -586,7 +588,7 @@ User has a shell script
 `/etc/kubernetes/node-feature-discovery/source.d/my-source` which has the
 following `stdout` output:
 
-```
+```plaintext
 MY_FEATURE_1
 MY_FEATURE_2=myvalue
 /override_source-OVERRIDE_BOOL
@@ -596,7 +598,7 @@ override.namespace/value=456
 
 which, in turn, will translate into the following node labels:
 
-```
+```plaintext
 feature.node.kubernetes.io/my-source-MY_FEATURE_1=true
 feature.node.kubernetes.io/my-source-MY_FEATURE_2=myvalue
 feature.node.kubernetes.io/override_source-OVERRIDE_BOOL=true
@@ -609,7 +611,7 @@ override.namespace/value=456
 User has a file `/etc/kubernetes/node-feature-discovery/features.d/my-source`
 which contains the following lines:
 
-```
+```plaintext
 MY_FEATURE_1
 MY_FEATURE_2=myvalue
 /override_source-OVERRIDE_BOOL
@@ -619,7 +621,7 @@ override.namespace/value=456
 
 which, in turn, will translate into the following node labels:
 
-```
+```plaintext
 feature.node.kubernetes.io/my-source-MY_FEATURE_1=true
 feature.node.kubernetes.io/my-source-MY_FEATURE_2=myvalue
 feature.node.kubernetes.io/override_source-OVERRIDE_BOOL=true
@@ -670,7 +672,7 @@ Example usage of the command line arguments, using a new namespace:
 The above would result in following extended resources provided that related
 labels exist:
 
-```
+```plaintext
   sgx.some.ns/epc: <label value>
   feature.node.kubernetes.io/my_source-my.feature: <label value>
 ```

docs/get-started/introduction.md

@@ -5,9 +5,11 @@ sort: 1
 ---
 
 # Introduction
+
 {: .no_toc }
 
 ## Table of Contents
+
 {: .no_toc .text-delta }
 
 1. TOC
@@ -90,6 +92,7 @@ NFD also annotates nodes it is running on:
 NOTE: the [`--instance`](../advanced/master-commandline-reference.md#instance)
 command line flag affects the annotation names
 
-Unapplicable annotations are not created, i.e. for example master.version is only created on nodes running nfd-master.
+Unapplicable annotations are not created, i.e. for example master.version is
+only created on nodes running nfd-master.
 
 

docs/mdl-style.rb

@@ -0,0 +1,6 @@
+all
+# Exclude MD041 - First line in file should be a top level header
+exclude_rule 'MD041'
+rule 'MD013', :tables => false
+rule 'MD013', :code_blocks => false
+rule 'MD024', :allow_different_nesting => true

scripts/test-infra/mdlint.sh

@@ -0,0 +1,7 @@
+#!/bin/bash -e
+
+# Install mdl
+gem install mdl -v 0.11.0
+
+# Run verify steps
+make mdlint