Browse Source

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>
(cherry picked from commit d5a26bd7e7)
changes/16/703316/1
Kevin Carter 1 month ago
parent
commit
07d2548395
1 changed files with 47 additions and 13 deletions
  1. +47
    -13
      doc/source/_exts/ansible-autodoc.py

+ 47
- 13
doc/source/_exts/ansible-autodoc.py View File

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

Loading…
Cancel
Save