From 50d06d9889fbc14b19850423122c6d53ed45ee25 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Thu, 20 Dec 2018 18:34:32 +0100 Subject: [PATCH] Docs: Show parameter types (in purple) (#49966) * Docs: Show parameter types (in purple) * Changes based on feedback * Remove leftover statement after review * Simplify TOC and support section * Add missing 'v' to version_added * Remove the v for version * Update docs/templates/plugin.rst.j2 Co-Authored-By: dagwieers * Update docs/templates/plugin.rst.j2 Co-Authored-By: dagwieers * Move Author into Support section * Avoid more "isn't included in any toctree" errors * Add Red Hat support section, list module status (cherry picked from commit 76450fd1c2052f5f8588b97e674aa2404f67cb04) --- docs/bin/plugin_formatter.py | 45 ++++++++------ .../templates/list_of_CATEGORY_modules.rst.j2 | 3 + docs/templates/plugin.rst.j2 | 61 +++++++++---------- 3 files changed, 56 insertions(+), 53 deletions(-) diff --git a/docs/bin/plugin_formatter.py b/docs/bin/plugin_formatter.py index ea5b073adb5..bebc33d29e4 100755 --- a/docs/bin/plugin_formatter.py +++ b/docs/bin/plugin_formatter.py @@ -1,22 +1,9 @@ #!/usr/bin/env python -# (c) 2012, Jan-Piet Mens -# (c) 2012-2014, Michael DeHaan and others -# (c) 2017 Ansible Project -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . +# Copyright: (c) 2012, Jan-Piet Mens +# Copyright: (c) 2012-2014, Michael DeHaan and others +# Copyright: (c) 2017, Ansible Project + +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type @@ -47,6 +34,7 @@ except ImportError: import jinja2 import yaml from jinja2 import Environment, FileSystemLoader +from jinja2.runtime import Undefined from six import iteritems, string_types from ansible.errors import AnsibleError @@ -158,6 +146,22 @@ def rst_xline(width, char="="): return char * width +def documented_type(text): + ''' Convert any python type to a type for documentation ''' + + if isinstance(text, Undefined): + return '-' + if text == 'str': + return 'string' + if text == 'bool': + return 'boolean' + if text == 'int': + return 'integer' + if text == 'dict': + return 'dictionary' + return text + + test_list = partial(is_sequence, include_strings=False) @@ -367,6 +371,7 @@ def jinja2_environment(template_dir, typ, plugin_type): env.filters['html_ify'] = html_ify env.filters['fmt'] = rst_fmt env.filters['xline'] = rst_xline + env.filters['documented_type'] = documented_type env.tests['list'] = test_list templates['plugin'] = env.get_template('plugin.rst.j2') @@ -464,14 +469,14 @@ def process_plugins(module_map, templates, outputname, output_dir, ansible_versi for (k, v) in iteritems(doc['options']): # Error out if there's no description if 'description' not in doc['options'][k]: - raise AnsibleError("Missing required description for option %s in %s " % (k, module)) + raise AnsibleError("Missing required description for parameter '%s' in '%s' " % (k, module)) # 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). required_value = doc['options'][k].get('required', False) if not isinstance(required_value, bool): - raise AnsibleError("Invalid required value '%s' for option '%s' in '%s' (must be truthy)" % (required_value, k, module)) + raise AnsibleError("Invalid required value '%s' for parameter '%s' in '%s' (must be truthy)" % (required_value, k, module)) # Strip old version_added information for options if 'version_added' in doc['options'][k] and too_old(doc['options'][k]['version_added']): diff --git a/docs/templates/list_of_CATEGORY_modules.rst.j2 b/docs/templates/list_of_CATEGORY_modules.rst.j2 index 808451b0b70..9d4c18b0f29 100644 --- a/docs/templates/list_of_CATEGORY_modules.rst.j2 +++ b/docs/templates/list_of_CATEGORY_modules.rst.j2 @@ -1,3 +1,6 @@ +{# avoids rST "isn't included in any toctree" errors for module docs #} +:orphan: + .. _@{ title.lower() + '_' + plugin_type + 's' }@: @{ title }@ @{ plugin_type + 's' }@ diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index 7e971a4c6ad..b1d32d7ba41 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -11,7 +11,7 @@ {% endfor %} {% if short_description %} -{% set title = module + ' - ' + short_description | rst_ify %} +{% set title = module + ' -- ' + short_description | rst_ify %} {% else %} {% set title = module %} {% endif %} @@ -25,7 +25,7 @@ .. contents:: :local: - :depth: 2 + :depth: 1 {# ------------------------------------------ # @@ -67,7 +67,7 @@ Aliases: @{ ','.join(aliases) }@ {% if requirements -%} Requirements -~~~~~~~~~~~~ +------------ {% if plugin_type == 'module' %} The below requirements are needed on the host that executes this @{ plugin_type }@. {% else %} @@ -118,9 +118,11 @@ Parameters {# parameter name with required and/or introduced label #} @{ key }@ - {% if value.get('type', None) %}
@{ value.type }@
{% endif %} - {% if value.get('required', False) %}
required
{% endif %} - {% if value.version_added %}
(added in @{value.version_added}@)
{% endif %} +
+ @{ value.type | documented_type }@ + {% if value.get('required', False) %} / required{% endif %} +
+ {% if value.version_added %}
added in @{value.version_added}@
{% endif %} {# default / choices #} @@ -135,7 +137,7 @@ Parameters {% endif %} {# Show possible choices and highlight details #} {% if value.choices %} -
    Choices: +
      Choices: {% for choice in value.choices %} {# Turn boolean values in 'yes' and 'no' values #} {% if choice is sameas true %} @@ -293,8 +295,8 @@ Facts returned by this module are added/updated in the ``hostvars`` host facts a {% endfor %} @{ key }@ -
      @{ value.type }@
      - {% if value.version_added %}
      (added in @{value.version_added}@)
      {% endif %} +
      @{ value.type | documented_type }@
      + {% if value.version_added %}
      added in @{value.version_added}@
      {% endif %} @{ value.returned | html_ify }@ @@ -365,8 +367,8 @@ Common return values are documented :ref:`here `, the foll {% endfor %} @{ key }@ -
      @{ value.type }@
      - {% if value.version_added %}
      (added in @{value.version_added}@)
      {% endif %} +
      @{ value.type | documented_type }@
      + {% if value.version_added %}
      added in @{value.version_added}@
      {% endif %} @{ value.returned | html_ify }@ @@ -405,53 +407,46 @@ Common return values are documented :ref:`here `, the foll Status ------ -{% if not deprecated %} + +{% if deprecated %} + +- This @{ plugin_type }@ will be removed in version @{ deprecated['removed_in'] | default('') | string | rst_ify }@. *[deprecated]* +- For more information see `DEPRECATED`_. + +{% else %} {% set support = { 'core': 'the Ansible Core Team', 'network': 'the Ansible Network Team', 'certified': 'an Ansible Partner', 'community': 'the Ansible Community', 'curated': 'a Third Party'} %} -{% set module_states = { 'preview': 'it is not guaranteed to have a backwards compatible interface', 'stableinterface': 'the maintainers for this module guarantee that no backward incompatible interface changes will be made'} %} +{% set module_states = { 'preview': 'not guaranteed to have a backwards compatible interface', 'stableinterface': 'guaranteed to have no backward incompatible interface changes going forward'} %} {% if metadata %} {% if metadata.status %} {% for cur_state in metadata.status %} -This @{ plugin_type }@ is flagged as **@{cur_state}@** which means that @{module_states[cur_state]}@. +- This @{ plugin_type }@ is @{ module_states[cur_state] }@. *[@{ cur_state }@]* {% endfor %} {% endif %} {% if metadata.supported_by %} - -Maintenance ------------ - {% set supported_by = support[metadata.supported_by] %} -This @{ plugin_type }@ is flagged as **@{metadata.supported_by}@** which means that it is maintained by @{ supported_by }@. See :ref:`Module Maintenance & Support ` for more info. - -For a list of other modules that are also maintained by @{ supported_by }@, see :ref:`here <@{ metadata.supported_by }@_supported>`. +- This @{ plugin_type }@ is :ref:`maintained by @{ supported_by }@ `. *[@{ metadata.supported_by }@]* {% if metadata.supported_by in ('core', 'network') %} +Red Hat Support +~~~~~~~~~~~~~~~ -Support -~~~~~~~ - -For more information about Red Hat's support of this @{ plugin_type }@, -please refer to this `Knowledge Base article `_ +More information about Red Hat's support of this @{ plugin_type }@ is available from this `Red Hat Knowledge Base article `_. {% endif %} {% endif %} {% endif %} -{% else %} - -This @{ plugin_type }@ is flagged as **deprecated** and will be removed in version @{ deprecated['removed_in'] | default('') | string | rst_ify }@. For more information see `DEPRECATED`_. - {% endif %} {% if author is defined -%} - -Author -~~~~~~ +Authors +~~~~~~~ {% for author_name in author %} - @{ author_name }@