From bdf392093af92da7d8fc4e32b68ff0716700522d Mon Sep 17 00:00:00 2001 From: Markus Heiser 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 --- 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 f35b86c41..6adba1037 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 5260da033..c1582cef2 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 f5957001c..8e54aef48 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 4dc1279f0..7c82ebe5a 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: