Establish stubs for documenting GitLab configuration.

Insert an `infrastructure` document under the `tools` node to own the
`jenkins` doc and a new `gitlab` doc.

Refs #3275

Change-Id: I4aa03949b4216290933716beb88b439a8a0940c4

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 4b26f87467a3157c43f2d93bcf4cf9073273f376..f3b9c4ad4f0690a0a775249605bcb1c98ee192c9 100644 (file)
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -338,9 +338,11 @@ if (SPHINX_FOUND)
         dev-manual/doxygen.rst
         dev-manual/error-handling.rst
         dev-manual/formatting.rst
+        dev-manual/gitlab.rst
         dev-manual/gmxtree.rst
         dev-manual/includestyle.rst
         dev-manual/index.rst
+        dev-manual/infrastructure.rst
         dev-manual/jenkins.rst
         dev-manual/known-issues.rst
         dev-manual/language-features.rst

diff --git a/docs/dev-manual/gitlab.rst b/docs/dev-manual/gitlab.rst
new file mode 100644 (file)
index 0000000..a3dd2bb
--- /dev/null
+++ b/docs/dev-manual/gitlab.rst
@@ -0,0 +1,22 @@
+GitLab
+======
+
+|Gromacs| is transitioning to GitLab for source code management, issue tracking,
+and integrated automation for testing and documentation.
+
+The repository contains DockerFiles and GitLab Runner configuration
+files to support automated testing and documentation builds.
+General information on configuring GitLab CI pipelines can be found
+in the official `Gitlab documentation <https://docs.gitlab.com/ee/ci/yaml/>`_.
+
+The GitLab CI configuration entry point is the :file:`.gitlab-ci.yml` file
+at the root of the source tree.
+Configuration templates are found in the files in the
+:file:`admin/ci-templates/` directory.
+
+Docker images used by GitLab Runner are available on `Docker Hub <https://hub.docker.com/u/gromacs>`__.
+Images are (re)built manually from DockerFiles in :file:`admin/dockerfiles`.
+
+This documentation is incomplete, pending resolution of :issue:`3275`.
+
+..  todo:: Expand this documentation to resolve :issue:`3275`

diff --git a/docs/dev-manual/infrastructure.rst b/docs/dev-manual/infrastructure.rst
new file mode 100644 (file)
index 0000000..8b33473
--- /dev/null
+++ b/docs/dev-manual/infrastructure.rst
@@ -0,0 +1,13 @@
+=============================
+Automation and Infrastructure
+=============================
+
+Through the 2020 release, automated testing and documentation builds are
+performed by a Jenkins installation. With the resolution of :issue:`3272`,
+|Gromacs| is transitioning to GitLab and GitLab Runner.
+
+..  toctree::
+    :maxdepth: 2
+
+    jenkins
+    gitlab

diff --git a/docs/dev-manual/jenkins.rst b/docs/dev-manual/jenkins.rst
index 65f2943e039e4eb8a84c1e7389c836c32b2c0e64..af7db95be2181ab5727fc3962c8c7d71e30e2d0e 100644 (file)
--- a/docs/dev-manual/jenkins.rst
+++ b/docs/dev-manual/jenkins.rst
@@ -1,8 +1,9 @@
 Understanding Jenkins builds
 ============================
 
-This page documents what different Jenkins builds actually run from the
-|Gromacs| source tree.  The purpose is two-fold:
+This page documents what different Jenkins builds actually run at
+http://jenkins.gromacs.org/ 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 (in most cases, referring to the

diff --git a/docs/dev-manual/releng/index.rst b/docs/dev-manual/releng/index.rst
index ac1ef91828bbb13c244c819bde9561e4568e0912..3bce2fb3e2b68ebd5985d78202608dc3c183911b 100644 (file)
--- a/docs/dev-manual/releng/index.rst
+++ b/docs/dev-manual/releng/index.rst
@@ -10,15 +10,13 @@ Release engineering with Gitlab
    :hidden:
 
 We are currently switching our build and testing system to use Gitlab
-and the integrated CI system, with information for the general system found
-in the official `Gitlab documentation <https://docs.gitlab.com/ee/ci/yaml/>`_.
-The new configuration for the builds and tests can be found in the file
-``.gitlab-ci.yml``, with the templates for configuring is found in the files in the
-``admin/ci-templates/`` directory. This section is going to be extended
+CI pipelines run on GitLab Runner. This section is going to be extended
 with individual build information as it comes available. For now we are
 using a combination of building with the previous system on Jenkins
 and post-submit verification on Gitlab.
 
+.. seealso:: :doc:`infrastructure`
+
 .. _releng-triggering-builds:
 
 Triggering builds on Gitlab

diff --git a/docs/dev-manual/tools.rst b/docs/dev-manual/tools.rst
index 9ce35b7ce585133440be9ada39341a3b09b34076..0fc35b1fbe1fd855c098543f0694f3d6f0ca2675 100644 (file)
--- a/docs/dev-manual/tools.rst
+++ b/docs/dev-manual/tools.rst
@@ -8,7 +8,7 @@ Several tools have their own individual pages and are listed below.
 
    doxygen
    change-management
-   jenkins
+   infrastructure
    releng/index
    gmxtree
    code-formatting
@@ -43,12 +43,11 @@ Gerrit
   All code changes go through a code review system at
   http://gerrit.gromacs.org.
 
-Jenkins
+Build testing
   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
+  checked on various platforms.
+  :doc:`infrastructure` documents how builds are automated,
+  providing information on how to replicate the builds (e.g., to
   diagnose issues).
   :doc:`releng/index` provides more information on the technical implementation
   of the builds.