From c6b6f269cc6fc5d77dae8e167ec0037e4c13c024 Mon Sep 17 00:00:00 2001
From: Ben Nemec <bnemec@redhat.com>
Date: Mon, 2 May 2016 01:21:32 -0500
Subject: [PATCH] Add documentation for dib-lint

Prior to this, no user documentation of dib-lint existed, which
meant users had to read the dib-lint code itself to figure out
how it worked.  This changes adds documentation on using dib-lint
and the checks it currently supports.

Change-Id: I285c5cc680dd9fbd9bd3f667ef102be14e248114
---
 doc/source/developer/dib_lint.rst | 51 +++++++++++++++++++++++++++++++
 doc/source/developer/index.rst    |  1 +
 2 files changed, 52 insertions(+)
 create mode 100644 doc/source/developer/dib_lint.rst

diff --git a/doc/source/developer/dib_lint.rst b/doc/source/developer/dib_lint.rst
new file mode 100644
index 00000000..d872dbde
--- /dev/null
+++ b/doc/source/developer/dib_lint.rst
@@ -0,0 +1,51 @@
+dib-lint
+========
+
+dib-lint provides a way to check for common errors in diskimage-builder
+elements.  To use it, simply run the ``dib-lint`` script in a directory
+containing an ``elements`` directory.  The checks will be run against
+every file found under ``elements``.
+
+The following is a list of what is currently caught by dib-lint:
+
+* executable: Ensure any files that begin with #! are executable
+* indent: Ensure that all source code is using an indent of four spaces
+* element-deps ordering: Ensure all element-deps files are alphabetized
+* /bin/bash: Ensure all scripts are using bash explicitly
+* sete: Ensure all scripts are set -e
+* setu: Ensure all scripts are set -u
+* setpipefail: Ensure all scripts are set -o pipefail
+* dibdebugtrace: Ensure all scripts respect the DIB_DEBUG_TRACE variable
+* tabindent: Ensure no tabs are used for indentation
+* newline: Ensure that every file ends with a newline
+* mddocs: Ensure that only markdown-formatted documentation is used
+* yaml validation: Ensure that any yaml files in the repo have valid syntax
+
+Some of the checks can be omitted, either for an entire project or for an
+individual file.  Project exclusions go in tox.ini, using the following
+section format::
+
+    [dib-lint]
+    ignore=sete setpipefail
+
+This will cause the set -e and set -o pipefail checks to be ignored.
+
+File-specific exclusions are specified as a comment in the relevant file,
+using the following format::
+
+    # dib-lint: disable=sete setpipefail
+
+This will exclude the same tests, but only for the file in which the comment
+appears.
+
+Only some of the checks can be disabled.  The ones available for exclusion are:
+
+* executable
+* indent
+* sete
+* setu
+* setpipefail
+* dibdebugtrace
+* tabindent
+* newline
+* mddocs
diff --git a/doc/source/developer/index.rst b/doc/source/developer/index.rst
index c2aa4f25..470041bf 100644
--- a/doc/source/developer/index.rst
+++ b/doc/source/developer/index.rst
@@ -32,4 +32,5 @@ review`` to submit changes to the upstream gerrit.
    invocation
    caches
    developing_elements
+   dib_lint
    stable_interfaces