Add documentation for modular composes

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

@@ -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
 ========================
 

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.