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.
purpleidea · Feb 22, 2018 · cffdb06 · cffdb06
1 parent 837388a
commit cffdb06
Show file tree

Hide file tree

Showing 18 changed files with 313 additions and 44 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,20 +4,27 @@
 [docs/style-guide.md](../docs/style-guide.md)
 
 * commit message titles must be in the form:
+
 ```topic: Capitalized message with no trailing period```
+
 or:
+
 ```topic, topic2: Capitalized message with no trailing period```
 
 * golang code must be formatted according to the standard, please run:
+
 ```
 make gofmt		# formats the entire project correctly
 ```
+
 or format a single golang file correctly:
+
 ```
 gofmt -w yourcode.go
 ```
 
 * please rebase your patch against current git master:
+
 ```
 git checkout master
 git pull origin master
@@ -28,6 +35,7 @@ hub pull-request	# or submit with the github web ui
 ```
 
 * after a patch review, please ping @purpleidea so we know to re-review:
+
 ```
 # make changes based on reviews...
 git add -p		# add new changes

diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@
 [![Jenkins](https://img.shields.io/badge/jenkins-status-brightgreen.svg?style=flat-square)](https://ci.centos.org/job/purpleidea-mgmt/)
 
 ## Community:
+
 Come join us in the `mgmt` community!
 
 | Medium | Link |
@@ -18,6 +19,7 @@ Come join us in the `mgmt` community!
 | Mailing list | [mgmtconfig-list@redhat.com](https://www.redhat.com/mailman/listinfo/mgmtconfig-list) |
 
 ## Status:
+
 Mgmt is a next generation automation tool. It has similarities to other tools in
 the configuration management space, but has a fast, modern, distributed systems
 approach. The project contains an engine and a language.
@@ -28,6 +30,7 @@ With your help you'll be able to influence our design and get us to 1.0 sooner!
 Interested developers should read the [quick start guide](docs/quick-start-guide.md).
 
 ## Documentation:
+
 Please read, enjoy and help improve our documentation!
 
 | Documentation | Additional Notes |
@@ -44,25 +47,28 @@ Please read, enjoy and help improve our documentation!
 | [development](docs/development.md) | for mgmt developers |
 
 ## Questions:
+
 Please ask in the [community](#community)!
 If you have a well phrased question that might benefit others, consider asking it by sending a patch to the [FAQ](docs/faq.md) section. I'll merge your question, and a patch with the answer!
 
 ## Roadmap:
+
 Feel free to grab one of the straightforward [#mgmtlove](https://github.com/purpleidea/mgmt/labels/mgmtlove) issues if you're a first time contributor to the project or if you're unsure about what to hack on!
 Please see: [TODO.md](TODO.md) for a list of upcoming work and TODO items.
 Please get involved by working on one of these items or by suggesting something else!
 
 ## Bugs:
+
 Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/blob/master/main.go) to `true`, and post the logs when you report the [issue](https://github.com/purpleidea/mgmt/issues).
 Bonus points if you provide a [shell](https://github.com/purpleidea/mgmt/tree/master/test/shell) or [OMV](https://github.com/purpleidea/mgmt/tree/master/test/omv) reproducible test case.
 Feel free to read my article on [debugging golang programs](https://purpleidea.com/blog/2016/02/15/debugging-golang-programs/).
 
 ## Patches:
+
 We'd love to have your patches! Please send them by email, or as a pull request.
 
 ## On the web:
-[Read what people are saying and publishing about mgmt!](docs/on-the-web.md)
 
-##
+[Read what people are saying and publishing about mgmt!](docs/on-the-web.md)
 
 Happy hacking!
diff --git a/TODO.md b/TODO.md
@@ -1,66 +1,84 @@
 # TODO
+
 If you're looking for something to do, look here!
 Let us know if you're working on one of the items.
 If you'd like something to work on, ping @purpleidea and I'll create an issue
 tailored especially for you! Just let me know your approximate golang skill
 level and how many hours you'd like to spend on the patch.
 
 ## Package resource
+
 - [ ] getfiles support on debian [bug](https://github.com/hughsie/PackageKit/issues/118)
 - [ ] directory info on fedora [bug](https://github.com/hughsie/PackageKit/issues/117)
 - [ ] dnf blocker [bug](https://github.com/hughsie/PackageKit/issues/110)
 
 ## File resource [bug](https://github.com/purpleidea/mgmt/issues/64) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
+
 - [ ] recurse limit support [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 - [ ] fanotify support [bug](https://github.com/go-fsnotify/fsnotify/issues/114)
 
 ## Svc resource
+
 - [ ] base resource improvements
 
 ## Exec resource
+
 - [ ] base resource improvements
 
 ## Timer resource
+
 - [ ] increment algorithm (linear, exponential, etc...) [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## User/Group resource
+
 - [ ] automatic edges to file resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Virt (libvirt) resource
+
 - [ ] base resource improvements [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Net (systemd-networkd) resource
+
 - [ ] base resource
 
 ## Nspawn (systemd-nspawn) resource
+
 - [ ] base resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Mount (systemd-mount) resource
+
 - [ ] base resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Cron (systemd-timer) resource
+
 - [ ] base resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Http resource
+
 - [ ] base resource [:heart:](https://github.com/purpleidea/mgmt/labels/mgmtlove)
 
 ## Etcd improvements
+
 - [ ] fix embedded etcd master race
 
 ## Torrent/dht file transfer
+
 - [ ] base plumbing
 
 ## GPG/Auth improvements
+
 - [ ] base plumbing
 
 ## Language improvements
+
 - [ ] more core functions
 - [ ] automatic language formatter, ala `gofmt`
 - [ ] gedit/gnome-builder/gtksourceview syntax highlighting
 - [ ] vim syntax highlighting
 - [ ] emacs syntax highlighting
 
 ## Other
+
 - [ ] better error/retry handling
 - [ ] deb package target in Makefile
 - [ ] reproducible builds

diff --git a/docs/development.md b/docs/development.md
@@ -1,22 +1,32 @@
 # Development
-This document contains some additional information and help regarding developing `mgmt`. Useful tools, conventions, etc.
+
+This document contains some additional information and help regarding
+developing `mgmt`. Useful tools, conventions, etc.
 
 Be sure to read [quick start guide](docs/quick-start-guide.md) first.
 
 ## Testing
-This project has both unit tests in the form of golang tests and integration tests using shell scripting.
 
-Native golang tests are preferred over tests written in our shell testing framework. Please see https://golang.org/pkg/testing/ for more information.
+This project has both unit tests in the form of golang tests and integration
+tests using shell scripting.
+
+Native golang tests are preferred over tests written in our shell testing
+framework. Please see [https://golang.org/pkg/testing/](https://golang.org/pkg/testing/)
+for more information.
 
 To run all tests:
 
 ```
 make test
 ```
 
-There is a library of quick and small integration tests for the language and YAML related things, check out [`test/shell/`](/test/shell). Adding a test is as easy as copying one of the files in [`test/shell/`](/test/shell) and adapting it.
+There is a library of quick and small integration tests for the language and
+YAML related things, check out [`test/shell/`](/test/shell). Adding a test is as
+easy as copying one of the files in [`test/shell/`](/test/shell) and adapting
+it.
 
-This test suite won't run by default (unless when on CI server) and needs to be called explictly using:
+This test suite won't run by default (unless when on CI server) and needs to be
+called explictly using:
 
 ```
 make test-shell
@@ -28,4 +38,5 @@ Or run an individual shell test using:
 make test-shell-load0
 ```
 
-Tip: you can use TAB completion with `make` to quickly get a list of possible individual tests to run.
+Tip: you can use TAB completion with `make` to quickly get a list of possible
+individual tests to run.