comments

doc/rtd/reference/custom_modules.rst

@@ -1,9 +1,8 @@
 Custom Modules
 **************
 
-Our reference section contains support information for ``cloud-init``.
-This includes details on the network requirements, API definitions, support
-matrices and so on.
+This includes reference documentation on how to extend cloud-init with
+custom / out-of-tree functionality.
 
 -----
 

doc/rtd/reference/custom_modules/custom_cleaners.rst

@@ -9,20 +9,17 @@ the filesystem when the :ref:`cloud-init clean<cli_clean>` command is invoked.
 
 The :command:`clean` operation is typically performed by image creators
 when preparing a golden image for clone and redeployment. The clean command
-removes any cloud-init semaphores, allowing cloud-init to treat the next
-boot of this image as the "first boot". When the image is next booted
-cloud-init will performing all initial configuration based on any valid
-datasource meta-data and user-data.
-
+removes any cloud-init internal state, allowing cloud-init to treat the next
+boot of this image as the "first boot".
 Any executable scripts in this subdirectory will be invoked in lexicographical
-order with run-parts when running the :command:`clean` command.
-
-Typical format of such scripts would be a ##-<some-app> like the following:
-:file:`/etc/cloud/clean.d/99-live-installer`
+order when running the :command:`clean` command.
 
-An example of a script is:
+Example
+=======
 
 .. code-block:: bash
 
+   $ cat /etc/cloud/clean.d/99-live-installer
+   #!/bin/sh
    sudo rm -rf /var/lib/installer_imgs/
    sudo rm -rf /var/log/installer/

doc/rtd/reference/custom_modules/custom_configuration_module.rst

@@ -9,10 +9,15 @@ by:
 #. :ref:`Implement a config module<module_creation>` in a Python file with its
    name starting with ``cc_``.
 
-#. Place the file where the rest of config modules are
+#. Place the file where the rest of config modules are located.
    On Ubuntu this path is typically:
    `/usr/lib/python3/dist-packages/cloudinit/config/`.
 
 #. Extend the :ref:`base-configuration's <base_config_module_keys>`
    ``cloud_init_modules``, ``cloud_config_modules`` or ``cloud_final_modules``
    to let the config module run on one of those stages.
+
+.. warning ::
+   The config jsonschema validation functionality is going to complain about
+   unknown config keys introduced by custom modules and there is not an easy
+   way for custom modules to define their keys schema-wise.

doc/rtd/reference/custom_modules/custom_datasource.rst

@@ -10,7 +10,7 @@ Custom 3rd-party out-of-tree DataSources can be added to cloud-init by:
 #. Place that file in as a single Python module or package in folder included
    in ``$PYTHONPATH``.
 
-#. Extend the :ref:`base-configuration<base_config_reference>`'s
+#. Extend the base configuration's
    :ref:`datasource_pkg_list<base_config_datasource_pkg_list>` to include the
    Python package where the DataSource is located.
 

doc/rtd/reference/custom_modules/custom_mergers.rst

@@ -3,12 +3,9 @@
 Custom Mergers
 **************
 
-TODO adapt and backreference
-
-Because the default
-:ref:`merging<merging_user_data>`
-algorithms and stragies may not always be desired,
-the concept of customised merging was introduced through `merge classes`.
+It is possible for users to inject their own :ref:`merging<merging_user_data>`
+files to handle specific types of merging as they choose (the
+basic ones included will handle lists, dicts, and strings).
 
 A `merge class` is a class definition providing functions that can be used
 to merge a given type with another given type.
@@ -47,7 +44,7 @@ An example of one of these `merging classes` is the following:
                    merged[k] = v
            return merged
 
-As you can see, there is an ``_on_dict`` method here that will be given a
+There is an ``_on_dict`` method here that will be given a
 source value, and a value to merge with. The result will be the merged object.
 
 This code itself is called by another merging class which "directs" the
@@ -56,10 +53,7 @@ find a known object that will merge that type. An example of this can be found
 in the :file:`mergers/__init__.py` file (see ``LookupMerger`` and
 ``UnknownMerger``).
 
-So, following the typical ``cloud-init`` approach of allowing source code to
-be downloaded and used dynamically, it is possible for users to inject their
-own merging files to handle specific types of merging as they choose (the
-basic ones included will handle lists, dicts, and strings). Note how each
+Note how each
 merge can have options associated with it, which affect how the merging is
 performed. For example, a dictionary merger can be told to overwrite instead
 of attempting to merge, or a string merger can be told to append strings