openstack
/
tripleo-ansible
Code Issues Proposed changes

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>
This commit is contained in:
Kevin Carter 2020-01-08 15:52:14 -06:00
parent ec7463550b
commit d5a26bd7e7
1 changed files with 47 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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