From d5a26bd7e7be99f7757b3f8ffbd66b437dad9344 Mon Sep 17 00:00:00 2001
From: Kevin Carter <kecarter@redhat.com>
Date: Wed, 8 Jan 2020 15:52:14 -0600
Subject: [PATCH] Allow comments in variable files to be rendered in docs

This change will allow all comments in our variable files to be rendered
normally within our documentation. This will allow folks reading our
documentation to benifit from information we may put in the various
files.

Change-Id: I0ce554651916f2b942dc0fd9f647d5a348042203
Signed-off-by: Kevin Carter <kecarter@redhat.com>
---
 doc/source/_exts/ansible-autodoc.py | 60 ++++++++++++++++++++++-------
 1 file changed, 47 insertions(+), 13 deletions(-)

diff --git a/doc/source/_exts/ansible-autodoc.py b/doc/source/_exts/ansible-autodoc.py
index 79f0a9d79..5b78e12c7 100644
--- a/doc/source/_exts/ansible-autodoc.py
+++ b/doc/source/_exts/ansible-autodoc.py
@@ -26,6 +26,45 @@ from docutils.writers.html4css1 import Writer
 from sphinx import addnodes
 
 import yaml
+from ruamel.yaml import YAML as RYAML
+
+try:
+    import io
+    StringIO = io.StringIO
+except ImportError:
+    import StringIO
+
+
+class DocYaml(RYAML):
+    def _license_filter(self, data):
+        """This will filter out our boilerplate license heading in return data.
+
+        The filter is used to allow documentation we're creating in variable
+        files to be rendered more beautifully.
+        """
+        lines = list()
+        mark = True
+        for line in data.splitlines():
+            if '# Copyright' in line:
+                mark = False
+            if mark:
+                lines.append(line)
+            if '# under the License' in line:
+                mark = True
+        return '\n'.join(lines)
+
+    def dump(self, data, stream=None, **kw):
+        if not stream:
+            stream = StringIO()
+        try:
+            RYAML.dump(self, data, stream, **kw)
+            return self._license_filter(stream.getvalue().strip())
+        finally:
+            stream.close()
+
+
+DOCYAML = DocYaml()
+DOCYAML.default_flow_style = False
 
 
 class AnsibleAutoPluginDirective(Directive):
@@ -99,7 +138,7 @@ class AnsibleAutoPluginDirective(Directive):
 
     @staticmethod
     def build_documentation(module):
-        docs = yaml.safe_load(module.DOCUMENTATION)
+        docs = DOCYAML.load(module.DOCUMENTATION)
         doc_data = dict()
         doc_data['docs'] = docs['description']
         doc_data['author'] = docs.get('author', list())
@@ -108,12 +147,10 @@ class AnsibleAutoPluginDirective(Directive):
 
     @staticmethod
     def build_examples(module):
-        examples = yaml.safe_load(module.EXAMPLES)
+        examples = DOCYAML.load(module.EXAMPLES)
         return_examples = list()
         for example in examples:
-            return_examples.append(
-                yaml.safe_dump([example], default_flow_style=False)
-            )
+            return_examples.append(DOCYAML.dump([example]))
         return return_examples
 
     def _raw_html_block(self, data):
@@ -137,10 +174,7 @@ class AnsibleAutoPluginDirective(Directive):
     def _literal_block(data, language='yaml', dump_data=True):
         if dump_data:
             literal = nodes.literal_block(
-                text=yaml.safe_dump(
-                    data,
-                    default_flow_style=False
-                )
+                text=DOCYAML.dump(data)
             )
         else:
             literal = nodes.literal_block(text=data)
@@ -179,7 +213,7 @@ class AnsibleAutoPluginDirective(Directive):
         defaults_file = os.path.join(role, 'defaults', 'main.yml')
         if os.path.exists(defaults_file):
             with open(defaults_file) as f:
-                role_defaults = yaml.safe_load(f.read())
+                role_defaults = DOCYAML.load(f.read())
             section.append(
                 self._yaml_section(
                     to_yaml_data=role_defaults,
@@ -197,7 +231,7 @@ class AnsibleAutoPluginDirective(Directive):
             for v_file in os.listdir(vars_path):
                 vars_file = os.path.join(vars_path, v_file)
                 with open(vars_file) as f:
-                    vars_values = yaml.safe_load(f.read())
+                    vars_values = DOCYAML.load(f.read())
                 section.append(
                     self._yaml_section(
                         to_yaml_data=vars_values,
@@ -227,7 +261,7 @@ class AnsibleAutoPluginDirective(Directive):
                     'molecule.yml'
                 )
                 with open(molecule_file) as f:
-                    molecule_conf = yaml.safe_load(f.read())
+                    molecule_conf = DOCYAML.load(f.read())
 
                 driver_data = molecule_conf.get('driver')
                 if driver_data:
@@ -265,7 +299,7 @@ class AnsibleAutoPluginDirective(Directive):
                     'playbook.yml'
                 )
                 with open(molecule_playbook_path) as f:
-                    molecule_playbook = yaml.safe_load(f.read())
+                    molecule_playbook = DOCYAML.load(f.read())
                 molecule_section.append(
                     self._yaml_section(
                         to_yaml_data=molecule_playbook,