test, docs: Add a linter for testing markdown, and fix up our docs

While writing docs, I couldn't remember what the correct style was
supposed to be, and I remember someone complaining about this
previously, so I decided to add a linter! I excluded a bunch of annoying
style rules, but if we find more we can add those to the list too.

Hopefully this gives us a more consistent feel throughout.

docs/documentation.md

@@ -136,15 +136,15 @@ Invoke `mgmt` with the `--puppet` switch, which supports 3 variants:
 
 1. Request the configuration from the Puppet Master (like `puppet agent` does)
 
-        mgmt run --puppet agent
+	`mgmt run --puppet agent`
 
 2. Compile a local manifest file (like `puppet apply`)
 
-        mgmt run --puppet /path/to/my/manifest.pp
+	`mgmt run --puppet /path/to/my/manifest.pp`
 
 3. Compile an ad hoc manifest from the commandline (like `puppet apply -e`)
 
-        mgmt run --puppet 'file { "/etc/ntp.conf": ensure => file }'
+	`mgmt run --puppet 'file { "/etc/ntp.conf": ensure => file }'`
 
 For more details and caveats see [Puppet.md](Puppet.md).
 
@@ -154,33 +154,40 @@ An introductory post on the Puppet support is on
 [Felix's blog](http://ffrank.github.io/features/2016/06/19/puppet-powered-mgmt/).
 
 ## Reference
+
 Please note that there are a number of undocumented options. For more
 information on these options, please view the source at:
 [https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/).
 If you feel that a well used option needs documenting here, please patch it!
 
 ### Overview of reference
+
 * [Meta parameters](#meta-parameters): List of available resource meta parameters.
 * [Graph definition file](#graph-definition-file): Main graph definition file.
 * [Command line](#command-line): Command line parameters.
 * [Compilation options](#compilation-options): Compilation options.
 
 ### Meta parameters
+
 These meta parameters are special parameters (or properties) which can apply to
 any resource. The usefulness of doing so will depend on the particular meta
 parameter and resource combination.
 
 #### AutoEdge
+
 Boolean. Should we generate auto edges for this resource?
 
 #### AutoGroup
+
 Boolean. Should we attempt to automatically group this resource with others?
 
 #### Noop
+
 Boolean. Should the Apply portion of the CheckApply method of the resource
 make any changes? Noop is a concatenation of no-operation.
 
 #### Retry
+
 Integer. The number of times to retry running the resource on error. Use -1 for
 infinite. This currently applies for both the Watch operation (which can fail)
 and for the CheckApply operation. While they could have separate values, I've
@@ -188,6 +195,7 @@ decided to use the same ones for both until there's a proper reason to want to
 do something differently for the Watch errors.
 
 #### Delay
+
 Integer. Number of milliseconds to wait between retries. The same value is
 shared between the Watch and CheckApply retries. This currently applies for both
 the Watch operation (which can fail) and for the CheckApply operation. While
@@ -196,6 +204,7 @@ until there's a proper reason to want to do something differently for the Watch
 errors.
 
 #### Poll
+
 Integer. Number of seconds to wait between `CheckApply` checks. If this is
 greater than zero, then the standard event based `Watch` mechanism for this
 resource is replaced with a simple polling mechanism. In general, this is not
@@ -213,6 +222,7 @@ which is another way of saying that if the resource finally settles down to give
 the graph enough time, it can probably converge.
 
 #### Limit
+
 Float. Maximum rate of `CheckApply` runs started per second. Useful to limit
 an especially _eventful_ process from causing excessive checks to run. This
 defaults to `+Infinity` which adds no limiting. If you change this value, you
@@ -220,12 +230,14 @@ will also need to change the `Burst` value to a non-zero value. Please see the
 [rate](https://godoc.org/golang.org/x/time/rate) package for more information.
 
 #### Burst
+
 Integer. Burst is the maximum number of runs which can happen without invoking
 the rate limiter as designated by the `Limit` value. If the `Limit` is not set
 to `+Infinity`, this must be a non-zero value. Please see the
 [rate](https://godoc.org/golang.org/x/time/rate) package for more information.
 
 #### Sema
+
 List of string ids. Sema is a P/V style counting semaphore which can be used to
 limit parallelism during the CheckApply phase of resource execution. Each
 resource can have `N` different semaphores which share a graph global namespace.
@@ -237,30 +249,37 @@ id's include: `some_id`, `hello:42`, `not:smart:4` and `:13`. It is expected
 that the last bare example be only used by the engine to add a global semaphore.
 
 ### Graph definition file
+
 graph.yaml is the compiled graph definition file. The format is currently
 undocumented, but by looking through the [examples/](https://github.com/purpleidea/mgmt/tree/master/examples)
 you can probably figure out most of it, as it's fairly intuitive.
 
 ### Command line
+
 The main interface to the `mgmt` tool is the command line. For the most recent
 documentation, please run `mgmt --help`.
 
 #### `--yaml <graph.yaml>`
+
 Point to a graph file to run.
 
 #### `--converged-timeout <seconds>`
+
 Exit if the machine has converged for approximately this many seconds.
 
 #### `--max-runtime <seconds>`
+
 Exit when the agent has run for approximately this many seconds. This is not
 generally recommended, but may be useful for users who know what they're doing.
 
 #### `--noop`
+
 Globally force all resources into no-op mode. This also disables the export to
 etcd functionality, but does not disable resource collection, however all
 resources that are collected will have their individual noop settings set.
 
 #### `--sema <size>`
+
 Globally add a counting semaphore of this size to each resource in the graph.
 The semaphore will get given an id of `:size`. In other words if you specify a
 size of 42, you can expect a semaphore if named: `:42`. It is expected that
@@ -270,38 +289,46 @@ than zero at this time. The traditional non-parallel execution found in config
 management tools such as `Puppet` can be obtained with `--sema 1`.
 
 #### `--remote <graph.yaml>`
+
 Point to a graph file to run on the remote host specified within. This parameter
 can be used multiple times if you'd like to remotely run on multiple hosts in
 parallel.
 
 #### `--allow-interactive`
+
 Allow interactive prompting for SSH passwords if there is no authentication
 method that works.
 
 #### `--ssh-priv-id-rsa`
+
 Specify the path for finding SSH keys. This defaults to `~/.ssh/id_rsa`. To
 never use this method of authentication, set this to the empty string.
 
 #### `--cconns`
+
 The maximum number of concurrent remote ssh connections to run. This defaults
 to `0`, which means unlimited.
 
 #### `--no-caching`
+
 Don't allow remote caching of the remote execution binary. This will require
 the binary to be copied over for every remote execution, but it limits the
 likelihood that there is leftover information from the configuration process.
 
 #### `--prefix <path>`
+
 Specify a path to a custom working directory prefix. This directory will get
 created if it does not exist. This usually defaults to `/var/lib/mgmt/`. This
 can't be combined with the `--tmp-prefix` option. It can be combined with the
 `--allow-tmp-prefix` option.
 
 #### `--tmp-prefix`
+
 If this option is specified, a temporary prefix will be used instead of the
 default prefix. This can't be combined with the `--prefix` option.
 
 #### `--allow-tmp-prefix`
+
 If this option is specified, we will attempt to fall back to a temporary prefix
 if the primary prefix couldn't be created. This is useful for avoiding failures
 in environments where the primary prefix may or may not be available, but you'd
@@ -338,12 +365,14 @@ GOTAGS="noaugeas novirt" make build
 ```
 
 ## Examples
+
 For example configurations, please consult the [examples/](https://github.com/purpleidea/mgmt/tree/master/examples) directory in the git
 source repository. It is available from:
 
 [https://github.com/purpleidea/mgmt/tree/master/examples](https://github.com/purpleidea/mgmt/tree/master/examples)
 
 ### Systemd:
+
 See [`misc/mgmt.service`](misc/mgmt.service) for a sample systemd unit file.
 This unit file is part of the RPM.