Initial docs for Jenkins integration

Add basic documentation for (some) of the Jenkins builds from the
perspective of how they interact with the build system.  This part
cannot change without changes in the build system and so can be
documented in the same repository as the build system.  And the
developer guide is a place where people would (hopefully) first look for
this kind of information.  Links can be provided to more documentation
on Jenkins usage and other configuration (e.g., on the wiki), once that
stabilizes.

Related to #1731.

Change-Id: I87e180d12a77c692ac4594b6c062fb6ca150aa5d

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 9f08d24e69dc224d2c71e86e2231d59d76493a8b..9c392812498460d9bd4f00660d4017f39cad0cff 100644 (file)
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -104,6 +104,7 @@ if (SPHINX_FOUND)
         dev-manual/formatting.rst
         dev-manual/gmxtree.rst
         dev-manual/includestyle.rst
+        dev-manual/jenkins.rst
         dev-manual/naming.rst
         dev-manual/overview.rst
         dev-manual/relocatable-binaries.rst

diff --git a/docs/dev-manual/jenkins.rst b/docs/dev-manual/jenkins.rst
new file mode 100644 (file)
index 0000000..13d0cc9
--- /dev/null
+++ b/docs/dev-manual/jenkins.rst
@@ -0,0 +1,81 @@
+Understaning Jenkins builds
+===========================
+
+This page documents what different Jenkins builds actually run from the
+|Gromacs| source tree.  The purpose is two-fold:
+
+* Provide information on how to interpret Jenkins failures and how to run the
+  same tasks locally to diagnose issues.
+* Provide information on what changes in the build system (or other parts of
+  the repository) need special care to not break Jenkins builds.
+
+.. TODO: Add a link to a wiki page about general Jenkins documentation, once
+   there is more of that.
+
+cppcheck build
+--------------
+
+This build runs the :command:`cppcheck` static analysis tool.  Any issues found
+mark the build unstable, and can be browsed in Jenkins.
+
+It runs :command:`cmake` to generate the build system, and then builds the
+``cppcheck`` target.  Nothing is compiled by this target, it only runs
+:command:`cppcheck` for the designated source files.  The CMake configuration
+options do not affect the set of files checked, but they do affect the checked
+code through :file:`config.h` and such.
+
+Documentation build
+-------------------
+
+This build builds various types of documentation:
+
+* PDF reference manual using LaTeX
+* Doxygen documentation extracted from the source code
+* Set of HTML pages containing an installation guide, a user guide, and a
+  developer guide, as well as links to the above.  This set of HTML pages can
+  be browsed from Jenkins.
+* Man pages
+* INSTALL text file
+
+The last three require building the :file:`gmx` binary and running it, so
+compilation failures will also show in this build.
+All log files that contain warnings are archived as artifacts in the build, and
+presence of any warnings marks the build unstable.  Brief description of which
+part failed is reported back to Gerrit.
+
+Additionally, the build runs some source code checks that rely on the Doxygen
+documentation.  See the description of the ``check-source`` target in
+:doc:`gmxtree`.
+
+:doc:`doxygen` provides general guidelines for Doxygen usage, which can be
+helpful in understanding and solving Doxygen warnings and some of the
+``check-source`` issues.
+:doc:`includestyle` provides guidelines for #include order and style, which is
+another part of ``check-source`` checks.
+
+Technically, the documentation build runs :file:`admin/build-docs.sh`.
+See that file for details of what it exactly builds and how.  Most changes in the
+documentation build system will require changes in this script, but Jenkins
+configuration should be more static.
+
+uncrustify build
+----------------
+
+This build checks the source code for formatting such as consistent indentation
+and use of braces, as well as for copyright headers.  See :doc:`formatting` for
+the guidelines that are enforced.
+
+Technically, the build simply runs :file:`admin/uncrustify.sh` as ::
+
+  admin/uncrustify.sh check --rev=HEAD^
+
+to check the formatting in the changes for the commit.
+If the return value is non-zero (i.e., any changes would be required), the
+build is marked unstable.
+Currently, only the console log of the build shows what actually was the issue.
+See :doc:`uncrustify` for more details on the script and uncrustify.
+
+.. TODO: Provide links to the build system page, once there are on the git
+   commit chain...
+
+.. TODO: Document all the rest.

diff --git a/docs/dev-manual/tools.rst b/docs/dev-manual/tools.rst
index 43bce33b84a9aec291064db0cdf34f401bade8e9..08a77a6312b3c247226a81cb340d53e14898d0b4 100644 (file)
--- a/docs/dev-manual/tools.rst
+++ b/docs/dev-manual/tools.rst
@@ -5,10 +5,15 @@ Development-time tools
    :maxdepth: 2
 
    doxygen
+   jenkins
    gmxtree
    uncrustify
    testutils
 
+.. TODO: Consider what is the most reasonable structure; currently, this list
+   here does not make much sense in the overall organization and creates a
+   confusing TOC for the developer guide.
+
 .. TODO: Add details for most of the tools, either in the form of links to wiki,
    or to a separate page that explains more details.
 
@@ -30,6 +35,9 @@ Jenkins
   All changes pushed to Gerrit are automatically compiled and otherwise
   checked on various platforms using a continuous integration system at
   http://jenkins.gromacs.org.
+  :doc:`jenkins` documents how Jenkins interacts with the build system,
+  providing information on how to replicate the builds Jenkins does (e.g., to
+  diagnose issues).
 
 Redmine
   Bugs and issues, as well as some random features and discussions,