cloud-init-dev team mailing list archive

[Chad Smith <chad.smith@xxxxxxxxxxxxx>]

Chad Smith has proposed merging ~chad.smith/cloud-init:fix-schema-shpinx-docs into cloud-init:master.

Requested reviews:
  cloud-init commiters (cloud-init-dev)

For more details, see:
https://code.launchpad.net/~chad.smith/cloud-init/+git/cloud-init/+merge/331118

docs: fix sphinx module schema documentation
  
Create a copy of each modules schema attribute when generating sphinx docs
to avoid altering the actual module dict in memory. This avoids illegible
rendering of module examples and distros where each character of a list
was represented on a separate line by itself.
   
Fixes ntp, resizefs, runcmd and bootcmd docs.

-- 
Your team cloud-init commiters is requested to review the proposed merge of ~chad.smith/cloud-init:fix-schema-shpinx-docs into cloud-init:master.

diff --git a/cloudinit/config/schema.py b/cloudinit/config/schema.py
index c17d973..bb291ff 100644
--- a/cloudinit/config/schema.py
+++ b/cloudinit/config/schema.py
@@ -8,6 +8,7 @@ from cloudinit.util import find_modules, read_file_or_url
 
 import argparse
 from collections import defaultdict
+from copy import deepcopy
 import logging
 import os
 import re
@@ -273,12 +274,13 @@ def get_schema_doc(schema):
     @param schema: Dict of jsonschema to render.
     @raise KeyError: If schema lacks an expected key.
     """
-    schema['property_doc'] = _get_property_doc(schema)
-    schema['examples'] = _get_schema_examples(schema)
-    schema['distros'] = ', '.join(schema['distros'])
+    schema_copy = deepcopy(schema)
+    schema_copy['property_doc'] = _get_property_doc(schema)
+    schema_copy['examples'] = _get_schema_examples(schema)
+    schema_copy['distros'] = ', '.join(schema['distros'])
     # Need an underbar of the same length as the name
-    schema['title_underbar'] = re.sub(r'.', '-', schema['name'])
-    return SCHEMA_DOC_TMPL.format(**schema)
+    schema_copy['title_underbar'] = re.sub(r'.', '-', schema['name'])
+    return SCHEMA_DOC_TMPL.format(**schema_copy)
 
 
 FULL_SCHEMA = None
diff --git a/tests/unittests/test_cli.py b/tests/unittests/test_cli.py
index 258a9f0..fccbbd2 100644
--- a/tests/unittests/test_cli.py
+++ b/tests/unittests/test_cli.py
@@ -125,6 +125,21 @@ class TestCLI(test_helpers.FilesystemMockingTestCase):
             'Expected either --config-file argument or --doc\n',
             self.stderr.getvalue())
 
+    def test_wb_devel_schema_subcommand_doc_content(self):
+        """Validate that doc content is sane from known examples."""
+        stdout = six.StringIO()
+        self.patchStdoutAndStderr(stdout=stdout)
+        self._call_main(['cloud-init', 'devel', 'schema', '--doc'])
+        expected_doc_sections = [
+            '**Supported distros:** all',
+            '**Supported distros:** centos, debian, fedora',
+            '**Config schema**:\n    **resize_rootfs:** (true/false/noblock)',
+            '**Examples**::\n\n    runcmd:\n        - [ ls, -l, / ]\n'
+        ]
+        stdout = stdout.getvalue()
+        for expected in expected_doc_sections:
+            self.assertIn(expected, stdout)
+
     @mock.patch('cloudinit.cmd.main.main_single')
     def test_single_subcommand(self, m_main_single):
         """The subcommand 'single' calls main_single with valid args."""