Merge branch 'documentation' into develop

doc/contributing.rst

@@ -121,6 +121,45 @@ For branches which are available to others, do a proper merge:
 
 This may require some manual conflict solving and will end up in a merge commit.
 
+--------------------------------------------------------------------------------
+|git| Hooks
+--------------------------------------------------------------------------------
+|git| hooks are scripts invoked by |git| in connection to certain commands.
+|project| currently provides one for :command:`commit`. It is installed by
+
+.. code-block:: console
+
+   $ cp extras/pre_commit/pre-commit .git/hooks/
+   $
+
+Its task is applying coding standards and doing a bunch of other checks on the
+files involved in a commit. Everything around the script is hosted in :file:`extras/pre_commit/`.
+
+If you ever have to skip the hook,
+
+.. code-block:: console
+
+   $ git commit --no-verify
+   $
+
+does the trick. **But** checks are always run on the complete file containing
+changes, not only on the lines changed. This means if you opt out of an issue,
+it will reappear next time that very file changes.
+
+For checking |python| code, the pre-commit hook employs |pylint|_, to make sure
+we stay close to |pep8|_. If you feel the need to make changes to the |pylint|
+call, please make sure you fully understand what the complaints are. Sometimes
+|pep8| sounds overly restrictive but it may help with performance and
+compatibility with |python| 3. For |project| it is also important that the code
+looks similar throughout the various modules. So do not disable a check because
+it just seems inconvenient or you do not understand why |pylint| is croaking at
+what looks like 'working' code. But then there are also cases where |pylint| is
+not smart enough to cope with valid |pep8| code. For changes with valid cause,
+the configuration flushed into |pylint| may be found at
+:file:`extras/pre_commit/pm3_csc/filecheck/pylintrc` and
+:file:`extras/pre_commit/pm3_csc/filecheck/pylint-unittest-rc`. The latter one
+is invoked on unit test code, where we may go a little bit less restrictive.
+
 --------------------------------------------------------------------------------
 Directory Structure
 --------------------------------------------------------------------------------
@@ -635,7 +674,10 @@ contributions to web pages using |project|.
 
 .. |fedora| replace:: Fedora
 .. |nameattr| replace:: :attr:`__name__`
-
+.. |pylint| replace:: Pylint
+.. _pylint: http://www.pylint.org
+.. |pep8| replace:: PEP 8
+.. _pep8: https://www.python.org/dev/peps/pep-0008/
 ..  LocalWords:  cmake hotfix doctest linkcheck rebase BRANCHNAME rebasing py
 ..  LocalWords:  CMakeLists txt rst pymod init submodule src restructuredtext
 ..  LocalWords:  makefiles formatters Changelog codetest promod sidechains io
@@ -646,4 +688,4 @@ contributions to web pages using |project|.
 ..  LocalWords:  SomethingTests testFileExistsFalse testutils RunTests DQMEAN
 ..  LocalWords:  pre API inline CMake hh ProMod Bienchen OST OPENSTRUCTURE
 ..  LocalWords:  mol alg conop QMEAN KIC eigen eigenvectors Lapack rawmodel
-..  LocalWords:  OpenStructure ost
+..  LocalWords:  OpenStructure ost pylint