diff options
author | Toshio Kuratomi <a.badger@gmail.com> | 2019-08-13 13:00:13 -0700 |
---|---|---|
committer | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2019-08-13 15:00:13 -0500 |
commit | d9b3af523b0eb7be3bf71cd1d9ff9e22d3596f6c (patch) | |
tree | 8b7f0d8788cee5b180c16dceabd7302f302589d6 /hacking | |
parent | 60f84836031f51af1b0807476e13a0a6313b7082 (diff) | |
download | ansible-d9b3af523b0eb7be3bf71cd1d9ff9e22d3596f6c.tar.gz |
Galaxy meta docs table (#60171)
* Use an rst table instead of a raw html table
* Rst is easier to read so we want to use it wherever possible
* Fix the jinja2 filters which create links so that they do not include
extraneous whitespace in the URL
* Normalize description data before sending them to the templates
Diffstat (limited to 'hacking')
3 files changed, 31 insertions, 8 deletions
diff --git a/hacking/build_library/build_ansible/command_plugins/collection_meta.py b/hacking/build_library/build_ansible/command_plugins/collection_meta.py index b28797473f..7b7112e8f9 100644 --- a/hacking/build_library/build_ansible/command_plugins/collection_meta.py +++ b/hacking/build_library/build_ansible/command_plugins/collection_meta.py @@ -12,18 +12,26 @@ import pathlib import yaml from jinja2 import Environment, FileSystemLoader +from ansible.module_utils.six import string_types from ansible.module_utils._text import to_bytes # Pylint doesn't understand Python3 namespace modules. from ..change_detection import update_file_if_different # pylint: disable=relative-beyond-top-level from ..commands import Command # pylint: disable=relative-beyond-top-level -from ..jinja2.filters import documented_type, html_ify # pylint: disable=relative-beyond-top-level +from ..jinja2.filters import documented_type, rst_ify # pylint: disable=relative-beyond-top-level DEFAULT_TEMPLATE_FILE = 'collections_galaxy_meta.rst.j2' DEFAULT_TEMPLATE_DIR = pathlib.Path(__file__).parents[4] / 'docs/templates' +def normalize_options(options): + """Normalize the options to make for easy templating""" + for opt in options: + if isinstance(opt['description'], string_types): + opt['description'] = [opt['description']] + + class DocumentCollectionMeta(Command): name = 'collection-meta' @@ -51,12 +59,14 @@ class DocumentCollectionMeta(Command): with open(args.collection_defs) as f: options = yaml.safe_load(f) + normalize_options(options) + env = Environment(loader=FileSystemLoader(template_dir), variable_start_string="@{", variable_end_string="}@", trim_blocks=True) env.filters['documented_type'] = documented_type - env.filters['html_ify'] = html_ify + env.filters['rst_ify'] = rst_ify template = env.get_template(template_file) output_name = os.path.join(output_dir, template_file.replace('.j2', '')) diff --git a/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py b/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py index 7407c97f99..1d2ed459f8 100644 --- a/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py +++ b/hacking/build_library/build_ansible/command_plugins/plugin_formatter.py @@ -386,8 +386,17 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi if field in doc and doc[field] in (None, ''): print("%s: WARNING: MODULE field '%s' DOCUMENTATION is null/empty value=%s" % (fname, field, doc[field])) + if 'description' in doc: + if isinstance(doc['description'], string_types): + doc['description'] = [doc['description']] + elif not isinstance(doc['description'], (list, tuple)): + raise AnsibleError("Description must be a string or list of strings. Got %s" + % type(doc['description'])) + else: + doc['description'] = [] + if 'version_added' not in doc: - display.error("*** ERROR: missing version_added in: %s ***\n" % module) + raise AnsibleError("*** ERROR: missing version_added in: %s ***\n" % module) # # The present template gets everything from doc so we spend most of this @@ -416,6 +425,14 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi if 'description' not in doc['options'][k]: raise AnsibleError("Missing required description for parameter '%s' in '%s' " % (k, module)) + # Make sure description is a list of lines for later formatting + if isinstance(doc['options'][k]['description'], string_types): + doc['options'][k]['description'] = [doc['options'][k]['description']] + elif not isinstance(doc['options'][k]['description'], (list, tuple)): + raise AnsibleError("Invalid type for options['%s']['description']." + " Must be string or list of strings. Got %s" % + (k, type(doc['options'][k]['description']))) + # Error out if required isn't a boolean (people have been putting # information on when something is required in here. Those need # to go in the description instead). @@ -427,10 +444,6 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi if 'version_added' in doc['options'][k] and too_old(doc['options'][k]['version_added']): del doc['options'][k]['version_added'] - # Make sure description is a list of lines for later formatting - if not isinstance(doc['options'][k]['description'], list): - doc['options'][k]['description'] = [doc['options'][k]['description']] - option_names.append(k) option_names.sort() diff --git a/hacking/build_library/build_ansible/jinja2/filters.py b/hacking/build_library/build_ansible/jinja2/filters.py index 735d07b7ba..21436eda90 100644 --- a/hacking/build_library/build_ansible/jinja2/filters.py +++ b/hacking/build_library/build_ansible/jinja2/filters.py @@ -27,7 +27,7 @@ _ITALIC = re.compile(r"I\(([^)]+)\)") _BOLD = re.compile(r"B\(([^)]+)\)") _MODULE = re.compile(r"M\(([^)]+)\)") _URL = re.compile(r"U\(([^)]+)\)") -_LINK = re.compile(r"L\(([^)]+),([^)]+)\)") +_LINK = re.compile(r"L\(([^)]+), *([^)]+)\)") _CONST = re.compile(r"C\(([^)]+)\)") _RULER = re.compile(r"HORIZONTALLINE") |