From 7b7b07211e00cb29687c02834547c5159fef03e3 Mon Sep 17 00:00:00 2001
From: Merlin Mathesius <mmathesi@redhat.com>
Date: Mar 19 2019 11:56:47 +0000
Subject: Add/improve documentation for scratch module build requests,

particularly for the new 'modulemd' and 'module_name' parameters.

Signed-off-by: Merlin Mathesius <mmathesi@redhat.com>

---

diff --git a/README.rst b/README.rst
index 2b53dd2..654f157 100644
--- a/README.rst
+++ b/README.rst
@@ -107,9 +107,15 @@ Options:
   existing requires on the modulemd. The expected format is ``{'platform': ['f28', 'f29']}``.
 - ``scratch`` - a boolean indicating if a scratch module build should be performed.
   Only allowed to be ``True`` if the MBS setting ``MODULES_ALLOW_SCRATCH`` is ``True``.
-- ``yaml`` - a string of the input file when submitting a YAML file directly in a
-  ``multipart/form-data`` request. The MBS setting ``YAML_SUBMIT_ALLOWED`` must be set to ``True``
-  for this to be allowed.
+- ``yaml`` - a string of the input file when submitting a YAML modulemd file directly in a
+  ``multipart/form-data`` request. Only allowed if ``scratch`` is ``True`` or if the MBS
+  setting ``YAML_SUBMIT_ALLOWED`` is ``True``. The basename of the file will be used as
+  the module name.
+- ``modulemd`` - a string for submitting a YAML modulemd file as a parameter in the JSON data as
+  an alternative to sending it in a ``multipart/form-data`` request. Only allowed if
+  ``scratch`` is ``True`` or if the MBS setting ``YAML_SUBMIT_ALLOWED`` is ``True``.
+- ``module_name`` - a string to use as the module name if a scratch build is requested and the
+  YAML modulemd is submitted using the ``modulemd`` parameter.
 - ``srpms`` - an optional list of Koji upload URLs of SRPMs to include in a module scratch build.
   Only allowed if ``scratch`` is ``True``.
 - ``rebuild_strategy`` - a string of the desired rebuild strategy (affects what components get
diff --git a/docs/HOW_MBS_BUILDS_MODULES.rst b/docs/HOW_MBS_BUILDS_MODULES.rst
index a15383d..896499e 100644
--- a/docs/HOW_MBS_BUILDS_MODULES.rst
+++ b/docs/HOW_MBS_BUILDS_MODULES.rst
@@ -19,7 +19,8 @@ This JSON data is handled by ``views.SCMHandler``, which validates the JSON and 
 ``submit_module_build(...)``.
 
 Alternatively, if submitting a YAML modulemd file is allowed (MBS setting
-``YAML_SUBMIT_ALLOWED`` is ``True``), the user can send a ``multipart/form-data``
+``YAML_SUBMIT_ALLOWED`` is ``True``), the user can include it in the JSON data
+(called ``modulemd`` and ``module_name``) or send a ``multipart/form-data``
 POST request directly including the contents of a YAML modulemd file
 (called ``yaml``). In this case, the JSON data and YAML file are handled by
 ``views.YAMLFileHandler``, which validates the data and calls the
@@ -27,7 +28,9 @@ POST request directly including the contents of a YAML modulemd file
 to ``submit_module_build(...)``.
 
 If module scratch builds are allowed (MBS setting ``MODULES_ALLOW_SCRATCH`` is
-``True``), the user can also upload one or more source RPMs uploaded to Koji
+``True``), the user can request a scratch module build (called ``scratch``).
+With a scratch build request, the user can include a YAML modulemd file
+(see above) and also upload one or more source RPMs to Koji
 via calls to Koji's ``session.uploadWrapper(..)``, and supply the list of
 upload links to MBS (called ``srpms``). Such custom SRPMs will be used to
 override the git repository source for corresponding components.