Update all role docs to use the ansible autodoc plugin

The ansible autodoc sphinx plugin has been updated to automatically
create role documentation for a given role. Because we can now auto
doc all of our roles, all roles with missing documentation have been
added.

Because the ansible autodoc plugin has been made more functional it
has been renamed.

The role addition playbook has been updated to use the new autodoc
module whenever a role is created.

Change-Id: I806217202884fc744fbb26a754617c0125be2857
Signed-off-by: Kevin Carter <kecarter@redhat.com>
changes/78/670678/2
Kevin Carter 4 years ago
parent c59f7a71fa
commit d9b2ee9f30
No known key found for this signature in database
GPG Key ID: CE94BD890A47B20A

@ -0,0 +1,322 @@
# Copyright 2019 Red Hat, Inc.
# All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import imp
import os
from docutils import core
from docutils import nodes
from docutils.parsers.rst import Directive
from docutils.parsers import rst
from docutils.writers.html4css1 import Writer
from sphinx import addnodes
import yaml
class AnsibleAutoPluginDirective(Directive):
directive_name = "ansibleautoplugin"
has_content = True
option_spec = {
'module': rst.directives.unchanged,
'role': rst.directives.unchanged,
'documentation': rst.directives.unchanged,
'examples': rst.directives.unchanged
}
@staticmethod
def _render_html(source):
return core.publish_parts(
source=source,
writer=Writer(),
writer_name='html',
settings_overrides={'no_system_messages': True}
)
def make_node(self, title, contents, content_type=None):
section = self._section_block(title=title)
if not content_type:
# Doc section
for content in contents['docs']:
for paragraph in content.split('\n'):
retnode = nodes.paragraph()
retnode.append(self._raw_html_block(data=paragraph))
section.append(retnode)
# Options Section
options_list = nodes.field_list()
options_section = self._section_block(title='Options')
for key, value in contents['options'].items():
options_list.append(
self._raw_fields(
data=value['description'],
field_name=key
)
)
else:
options_section.append(options_list)
section.append(options_section)
# Authors Section
authors_list = nodes.field_list()
authors_list.append(
self._raw_fields(
data=contents['author']
)
)
authors_section = self._section_block(title='Authors')
authors_section.append(authors_list)
section.append(authors_section)
elif content_type == 'yaml':
for content in contents:
section.append(
self._literal_block(
data=content,
dump_data=False
)
)
return section
@staticmethod
def load_module(filename):
return imp.load_source('__ansible_module__', filename)
@staticmethod
def build_documentation(module):
docs = yaml.safe_load(module.DOCUMENTATION)
doc_data = dict()
doc_data['docs'] = docs['description']
doc_data['author'] = docs.get('author', list())
doc_data['options'] = docs.get('options', dict())
return doc_data
@staticmethod
def build_examples(module):
examples = yaml.safe_load(module.EXAMPLES)
return_examples = list()
for example in examples:
return_examples.append(
yaml.safe_dump([example], default_flow_style=False)
)
return return_examples
def _raw_html_block(self, data):
html = self._render_html(source=data)
return nodes.raw('', html['body'], format='html')
def _raw_fields(self, data, field_name=''):
body = nodes.field_body()
if isinstance(data, list):
for item in data:
body.append(self._raw_html_block(data=item))
else:
body.append(self._raw_html_block(data=data))
field = nodes.field()
field.append(nodes.field_name(text=field_name))
field.append(body)
return field
@staticmethod
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
)
)
else:
literal = nodes.literal_block(text=data)
literal['language'] = 'yaml'
return literal
@staticmethod
def _section_block(title, text=None):
section = nodes.section(
title,
nodes.title(text=title),
ids=[nodes.make_id('-'.join(title))],
)
if text:
section_body = nodes.field_body()
section_body.append(nodes.paragraph(text=text))
section.append(section_body)
return section
def _yaml_section(self, to_yaml_data, section_title, section_text=None):
yaml_section = self._section_block(
title=section_title,
text=section_text
)
yaml_section.append(self._literal_block(data=to_yaml_data))
return yaml_section
def _run_role(self, role):
section = self._section_block(
title='Role Documentation',
text='Welcome to the "{}" role documentation.'.format(
os.path.basename(role)
)
)
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())
section.append(
self._yaml_section(
to_yaml_data=role_defaults,
section_title='Role Defaults',
section_text='This section highlights all of the defaults'
' and variables set within the "{}"'
' role.'.format(
os.path.basename(role)
)
)
)
vars_path = os.path.join(role, 'vars')
if os.path.exists(vars_path):
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())
section.append(
self._yaml_section(
to_yaml_data=vars_values,
section_title='Role Variables: {}'.format(v_file)
)
)
test_list = nodes.field_list()
test_section = self._section_block(
title='Molecule Scenarios',
text='Molecule is being used to test the "{}" role. The'
' following section highlights the drivers in service'
' and provides an example playbook showing how the role'
' is leveraged.'.format(
os.path.basename(role)
)
)
molecule_path = os.path.join(role, 'molecule')
if os.path.exists(molecule_path):
for test in os.listdir(molecule_path):
molecule_section = self._section_block(
title='Scenario: {}'.format(test)
)
molecule_file = os.path.join(
molecule_path,
test,
'molecule.yml'
)
with open(molecule_file) as f:
molecule_conf = yaml.safe_load(f.read())
driver_data = molecule_conf.get('driver')
if driver_data:
molecule_section.append(
nodes.field_name(
text='Driver: {}'.format(
driver_data['name']
)
)
)
options = driver_data.get('options')
if options:
molecule_section.append(
self._yaml_section(
to_yaml_data=options,
section_title='Molecule Options'
)
)
provisioner_data = molecule_conf.get('provisioner')
if provisioner_data:
inventory = provisioner_data.get('inventory')
if inventory:
molecule_section.append(
self._yaml_section(
to_yaml_data=inventory,
section_title='Molecule Inventory'
)
)
molecule_playbook_path = os.path.join(
molecule_path,
test,
'playbook.yml'
)
with open(molecule_playbook_path) as f:
molecule_playbook = yaml.safe_load(f.read())
molecule_section.append(
self._yaml_section(
to_yaml_data=molecule_playbook,
section_title='Example {} playbook'.format(test)
)
)
test_list.append(molecule_section)
else:
test_section.append(test_list)
section.append(test_section)
self.run_returns.append(section)
def _run_module(self, module):
if self.options.get('documentation'):
docs = self.build_documentation(module=module)
self.run_returns.append(
self.make_node(
title="Module Documentation",
contents=docs
)
)
if self.options.get('examples'):
examples = self.build_examples(module=module)
self.run_returns.append(
self.make_node(
title="Example Tasks",
contents=examples,
content_type='yaml'
)
)
def run(self):
self.run_returns = list()
if self.options.get('module'):
module = self.load_module(filename=self.options['module'])
self._run_module(module=module)
if self.options.get('role'):
self._run_role(role=self.options['role'])
return self.run_returns
def setup(app):
classes = [
AnsibleAutoPluginDirective,
]
for directive_class in classes:
app.add_directive(directive_class.directive_name, directive_class)
return {'version': '0.2'}

@ -1,175 +0,0 @@
# Copyright 2019 Red Hat, Inc.
# All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import imp
import os
from docutils import core
from docutils import nodes
from docutils.parsers.rst import Directive
from docutils.parsers import rst
from docutils.writers.html4css1 import Writer
from sphinx import addnodes
import yaml
class AnsibleAutoPluginDirective(Directive):
directive_name = "ansibleautoplugin"
has_content = True
option_spec = {
'module': rst.directives.unchanged_required,
'documentation': rst.directives.unchanged,
'examples': rst.directives.unchanged
}
@staticmethod
def _render_html(source):
return core.publish_parts(
source=source,
writer=Writer(),
writer_name='html',
settings_overrides={'no_system_messages': True}
)
def make_node(self, title, contents, content_type=None):
section = nodes.section(
title,
nodes.title(text=title),
ids=[nodes.make_id(__file__)],
)
if not content_type:
# Doc section
for content in contents['docs']:
for paragraph in content.split('\n'):
retnode = nodes.paragraph()
html = self._render_html(source=paragraph)
retnode += nodes.raw('', html['body'], format='html')
section.append(retnode)
# Options Section
options_list = nodes.field_list()
options_section = nodes.section(
'Options',
nodes.title(text='Options'),
ids=[nodes.make_id(__file__)],
)
for key, value in contents['options'].items():
body = nodes.field_body()
if isinstance(value['description'], list):
for desc in value['description']:
html = self._render_html(source=desc)
body.append(
nodes.raw('', html['body'], format='html')
)
else:
html = self._render_html(source=value['description'])
body.append(
nodes.raw('', html['body'], format='html')
)
field = nodes.field()
field.append(nodes.field_name(text=key))
field.append(body)
options_list.append(field)
else:
options_section.append(options_list)
section.append(options_section)
# Authors Section
authors_list = nodes.field_list()
authors_section = nodes.section(
'Authors',
nodes.title(text='Authors'),
ids=[nodes.make_id(__file__)],
)
field = nodes.field()
field.append(nodes.field_name(text=''))
for author in contents['author']:
body = nodes.field_body()
html = self._render_html(source=author)
body.append(
nodes.raw('', html['body'], format='html')
)
field.append(body)
else:
authors_list.append(field)
authors_section.append(authors_list)
section.append(authors_section)
elif content_type == 'yaml':
for content in contents:
retnode = nodes.literal_block(text=content)
retnode['language'] = 'yaml'
section.append(retnode)
return section
def load_module(self, filename):
return imp.load_source('__ansible_module__', filename)
def build_documentation(self, module):
docs = yaml.safe_load(module.DOCUMENTATION)
doc_data = dict()
doc_data['docs'] = docs['description']
doc_data['author'] = docs.get('author', list())
doc_data['options'] = docs.get('options', dict())
return doc_data
def build_examples(self, module):
examples = yaml.safe_load(module.EXAMPLES)
return_examples = list()
for example in examples:
return_examples.append(
yaml.safe_dump([example], default_flow_style=False)
)
return return_examples
def run(self):
module = self.load_module(filename=self.options['module'])
return_data = list()
if self.options.get('documentation'):
docs = self.build_documentation(module=module)
return_data.append(
self.make_node(
title="Module Documentation",
contents=docs
)
)
if self.options.get('examples'):
examples = self.build_examples(module=module)
return_data.append(
self.make_node(
title="Example Tasks",
contents=examples,
content_type='yaml'
)
)
return return_data
def setup(app):
classes = [
AnsibleAutoPluginDirective,
]
for directive_class in classes:
app.add_directive(directive_class.directive_name, directive_class)
return {'version': '0.1'}

@ -27,7 +27,7 @@ sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
extensions = [
'openstackdocstheme',
'sphinx.ext.autodoc',
'ansible-module-autodoc'
'ansible-autodoc'
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy

@ -2,22 +2,5 @@
Role - aide
===========
This role provides for the following services:
* aide
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/aide/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/aide/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/aide

@ -0,0 +1,6 @@
================================
Role - octavia-controller-config
================================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/octavia-controller-config

@ -0,0 +1,6 @@
===============================
Role - octavia-overcloud-config
===============================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/octavia-overcloud-config

@ -0,0 +1,6 @@
=====================================
Role - octavia-controller-post-config
=====================================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/octavia-controller-post-config

@ -0,0 +1,6 @@
=========================
Role - octavia-undercloud
=========================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/octavia-undercloud

@ -0,0 +1,6 @@
=====================
Role - octavia_common
=====================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/octavia_common

@ -2,14 +2,5 @@
Role - test_deps
================
This role provides for the following services:
* test_deps
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/test_deps/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/test_deps

@ -2,14 +2,5 @@
Role - test_json_error_callback
===============================
This role provides for the following services:
* test_json_error_callback
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/test_json_error_callback/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/test_json_error_callback

@ -2,14 +2,5 @@
Role - test_package_action
==========================
This role provides for the following services:
* test_package_action
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/test_package_action/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/test_package_action

@ -2,22 +2,5 @@
Role - tripleo-bootstrap
========================
This role provides for the following services:
* tripleo-bootstrap
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-bootstrap/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-bootstrap/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-bootstrap

@ -0,0 +1,6 @@
==========================
Role - tripleo-ceph-common
==========================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-ceph-common

@ -0,0 +1,6 @@
=============================
Role - tripleo-ceph-fetch-dir
=============================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-ceph-fetch-dir

@ -0,0 +1,6 @@
===============================
Role - tripleo-ceph-run-ansible
===============================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-ceph-run-ansible

@ -0,0 +1,6 @@
========================
Role - tripleo-ceph-uuid
========================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-ceph-uuid

@ -0,0 +1,6 @@
============================
Role - tripleo-ceph-work-dir
============================
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-ceph-work-dir

@ -2,30 +2,5 @@
Role - tripleo-container-rm
===========================
This role provides for the following services:
* tripleo-container-rm
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-container-rm/defaults/main.yml
:language: yaml
:start-after: under the License.
Example default playbook
~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-container-rm/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
Example docker playbook
~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-container-rm/molecule/podman/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-container-rm

@ -2,30 +2,5 @@
Role - tripleo-container-tag
============================
This role provides for the following services:
* tripleo-container-tag
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-container-tag/defaults/main.yml
:language: yaml
:start-after: under the License.
Example default playbook
~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-container-tag/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
Example podman playbook
~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-container-tag/molecule/podman/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-container-tag

@ -2,37 +2,5 @@
Role - tripleo-create-admin
===========================
This role provides for the following services:
* tripleo-create-admin
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-create-admin/defaults/main.yml
:language: yaml
:start-after: under the License.
Example default playbook
~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-create-admin/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
Example keygen playbook
~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-create-admin/molecule/keygen/playbook.yml
:language: yaml
:start-after: under the License.
Authorize existing user
^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-create-admin/molecule/addkey/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-create-admin

@ -2,11 +2,6 @@
Role - tripleo-docker-rm
========================
This role provides for the following services:
* tripleo-docker-rm
.. DANGER::
This role is a linked role to `tripleo-container-rm`. This role and exists
@ -15,17 +10,5 @@ This role provides for the following services:
`tripleo-container-rm`.
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-docker-rm/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-docker-rm/molecule/docker_rm/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-docker-rm

@ -2,22 +2,5 @@
Role - tripleo-image-serve
==========================
This role provides for the following services:
* tripleo-image-serve
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-image-serve/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-image-serve/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-image-serve

@ -2,30 +2,5 @@
Role - tripleo-module-load
==========================
This role provides for the following services:
* tripleo-module-load
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-module-load/defaults/main.yml
:language: yaml
:start-after: under the License.
Example default playbook
~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-module-load/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
Example module remove playbook
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-module-load/molecule/remove_module/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-module-load

@ -2,22 +2,5 @@
Role - tripleo-ssh-known-hosts
==============================
This role provides for the following services:
* tripleo-ssh-known-hosts
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-ssh-known-hosts/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-ssh-known-hosts/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-ssh-known-hosts

@ -2,22 +2,5 @@
Role - tripleo-transfer
=======================
This role provides for the following services:
* tripleo-transfer
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-transfer/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tripleo-transfer/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tripleo-transfer

@ -2,22 +2,5 @@
Role - tuned
============
This role provides for the following services:
* tuned
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tuned/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/tuned/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/tuned

@ -87,23 +87,6 @@
{{ opening }}
{{ '=' * (opening | length) }}
This role provides for the following services:
* {{ role_name }}
Default variables
~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/{{ role_name }}/defaults/main.yml
:language: yaml
:start-after: under the License.
Example playbook
~~~~~~~~~~~~~~~~
.. literalinclude:: ../../../tripleo_ansible/roles/{{ role_name }}/molecule/default/playbook.yml
:language: yaml
:start-after: under the License.
.. ansibleautoplugin::
:role: tripleo_ansible/roles/{{ role_name }}
dest: "doc/source/roles/role-{{ role_name }}.rst"

Loading…
Cancel
Save