From bdf392093af92da7d8fc4e32b68ff0716700522d Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Wed, 8 Jan 2020 18:09:36 +0100
Subject: [PATCH] build requirements: add a shell script static analysis tool

ShellCheck: https://github.com/koalaman/shellcheck

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 Makefile                  |  6 +++--
 docs/admin/buildhosts.rst | 50 ++++++++++++++++++++++++++++++++-------
 docs/dev/makefile.rst     |  4 +++-
 docs/dev/reST.rst         |  5 ++--
 4 files changed, 50 insertions(+), 15 deletions(-)

diff --git a/Makefile b/Makefile
index f35b86c4..6adba103 100644
--- a/Makefile
+++ b/Makefile
@@ -70,12 +70,14 @@ $(GH_PAGES)::
 # test
 # ----
 
-PHONY += test test.pylint test.pep8 test.unit test.robot
+PHONY += test test.sh test.pylint test.pep8 test.unit test.robot
 
 # TODO: balance linting with pylint
-test: test.pep8 test.unit test.robot
+test: test.pep8 test.unit test.sh test.robot
 	- make pylint
 
+test.sh:
+
 test.pep8: pyenvinstall
 	$(PY_ENV_ACT); ./manage.sh pep8_check
 
diff --git a/docs/admin/buildhosts.rst b/docs/admin/buildhosts.rst
index 5260da03..c1582cef 100644
--- a/docs/admin/buildhosts.rst
+++ b/docs/admin/buildhosts.rst
@@ -35,8 +35,17 @@ processing additional packages are needed.  The XeTeX_ needed not only for PDF
 creation, its also needed for :ref:`math` when HTML output is build.
 
 To be able to do :ref:`sphinx:math-support` without CDNs, the math are rendered
-as images (``sphinx.ext.imgmath`` extension).  If your docs build (``make
-docs``) shows warnings like this::
+as images (``sphinx.ext.imgmath`` extension).
+
+Here is the extract from the :origin:`docs/conf.py` file, setting math renderer
+to ``imgmath``:
+
+.. literalinclude:: ../conf.py
+   :language: python
+   :start-after: # sphinx.ext.imgmath setup
+   :end-before: # sphinx.ext.imgmath setup END
+
+If your docs build (``make docs``) shows warnings like this::
 
    WARNING: dot(1) not found, for better output quality install \
             graphviz from http://www.graphviz.org
@@ -47,8 +56,6 @@ docs``) shows warnings like this::
 you need to install additional packages on your build host, to get better HTML
 output.
 
-.. _system requirements:
-
 .. tabs::
 
    .. group-tab:: Ubuntu / debian
@@ -94,10 +101,35 @@ For PDF output you also need:
 	        texlive-collection-fontsrecommended texlive-collection-latex \
 		dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fonts
 
-.. _system requirements END:
+.. _sh lint:
 
-.. literalinclude:: ../conf.py
-   :language: python
-   :start-after: # sphinx.ext.imgmath setup
-   :end-before: # sphinx.ext.imgmath setup END
+Lint shell scripts
+==================
 
+.. _ShellCheck: https://github.com/koalaman/shellcheck
+
+To lint shell scripts, we use ShellCheck_ - A shell script static analysis tool.
+
+.. SNIP sh lint requirements
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code-block:: sh
+
+         $ sudo apt install shellcheck
+
+   .. group-tab:: Arch Linux
+
+      .. code-block:: sh
+
+         $ sudo pacman -S shellcheck
+
+   .. group-tab::  Fedora / RHEL
+
+      .. code-block:: sh
+
+         $ sudo dnf install ShellCheck
+
+.. SNAP sh lint requirements
diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst
index f5957001..8e54aef4 100644
--- a/docs/dev/makefile.rst
+++ b/docs/dev/makefile.rst
@@ -11,6 +11,8 @@ Makefile Targets
    Before looking deeper at the targets, first read about :ref:`makefile setup`
    and :ref:`make pyenv`.
 
+   To install system requirements follow :ref:`buildhosts`.
+
 With the aim to simplify development cycles, started with :pull:`1756` a
 ``Makefile`` based boilerplate was added.  If you are not familiar with
 Makefiles, we recommend to read gnu-make_ introduction.
@@ -170,7 +172,7 @@ e.g.:
 
 .. code:: sh
 
-  $ make test.pep8 test.unit
+  $ make test.pep8 test.unit test.sh
   . ./local/py3/bin/activate; ./manage.sh pep8_check
   [!] Running pep8 check
   . ./local/py3/bin/activate; ./manage.sh unit_tests
diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst
index 4dc1279f..7c82ebe5 100644
--- a/docs/dev/reST.rst
+++ b/docs/dev/reST.rst
@@ -1312,9 +1312,8 @@ others are basic-tabs_ and code-tabs_.  Below a *group-tab* example from
 
 .. literalinclude:: ../admin/buildhosts.rst
    :language: reST
-   :start-after: .. _system requirements:
-   :end-before: .. _system requirements END:
-
+   :start-after: .. SNIP sh lint requirements
+   :end-before: .. SNAP sh lint requirements
 
 .. _math: