From b068514471f6e7d718fe112432e5d142a0062048 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lubom=C3=ADr=20Sedl=C3=A1=C5=99?= <lsedlar@redhat.com>
Date: Mon, 20 Nov 2017 10:19:44 +0100
Subject: [PATCH] Add documentation for modular composes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

List all available configuration options and go into some detail on how
modules should be specified. This would probably deserver a more
thorough explanation, but it's still bit in a flux.

Fixes: https://pagure.io/pungi/issue/767
Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com>
---
 doc/configuration.rst | 26 +++++++++++++++++++++++++-
 doc/gathering.rst     | 22 ++++++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/doc/configuration.rst b/doc/configuration.rst
index ecfb46a1..46c85d2d 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -538,7 +538,11 @@ Options
 -------
 
 **gather_source** [mandatory]
-    (*str*) -- from where to read initial package list; expected values: "comps", "none"
+    (*str*) -- from where to read initial package list; expected values:
+    ``comps``, ``none``, ``module``
+
+    When ``comps`` is selected, you have to specify ``comps_file`` option. When
+    ``module`` is selected, you have to :ref:`configure PDC API url <pdc-settings>`.
 
 **gather_method** [mandatory]
     (*str*) -- Options are ``deps`` and ``nodeps``. Specifies whether package
@@ -1417,6 +1421,26 @@ Media Checksums Settings
     ``%(release_short)s-%(variant)s-%(version)s-%(date)s%(type_suffix)s.%(respin)s``.
 
 
+.. _pdc-settings:
+
+PDC Settings
+============
+
+Modular compose needs a PDC instance to talk to so that it can query list of
+module contents.
+
+**pdc_url**
+    (*str*) -- URL to the PDC API
+
+**pdc_develop** = ``False``
+    (*bool*) -- Turning this option on makes the client skip any authentication
+    assuming the server is open to anyone. This is useful for debugging against
+    a local instance, but you most likely do not want this in production.
+
+**pdc_insecure** = ``False``
+    (*bool*) -- Enable this to skip SSL certificate verification. This is a bad
+    idea in production.
+
 Translate Paths Settings
 ========================
 
diff --git a/doc/gathering.rst b/doc/gathering.rst
index 7a3b6803..5111f617 100644
--- a/doc/gathering.rst
+++ b/doc/gathering.rst
@@ -78,3 +78,25 @@ Profiling
 
 Profiling data on the ``pungi-gather`` tool can be enabled by setting the
 ``gather_profiler`` configuration option to ``True``.
+
+
+Modular compose
+===============
+
+A compose with ``gather_source`` set to ``module`` is called *modular*. The
+package list is determined by a list of modules.
+
+The list of modules that will be put into a variant is defined in the
+``variants.xml`` file. The file can contain either *Name:Stream* or
+*Name:Stream:Version* references. See `Module Naming Policy
+<https://pagure.io/modularity/blob/master/f/source/development/building-modules/naming-policy.rst>`_
+for details. When *Version* is missing from the specification, Pungi will ask
+PDC for the latest one.
+
+The module metadata in PDC contains a list of RPMs in the module as well as
+Koji tag from which the packages can be retrieved.
+
+Restrictions
+------------
+
+ * A modular compose must always use Koji as a package set source.