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 <dag@wieers.com>

* Update docs/templates/plugin.rst.j2

Co-Authored-By: dagwieers <dag@wieers.com>

* 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 76450fd1c2)

docs/bin/plugin_formatter.py

@@ -1,22 +1,9 @@
 #!/usr/bin/env python
-# (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
+# Copyright: (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
-# (c) 2012-2014, Michael DeHaan <michael@ansible.com> and others
+# Copyright: (c) 2012-2014, Michael DeHaan <michael@ansible.com> and others
-# (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
-#
+
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# 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 <http://www.gnu.org/licenses/>.
 
 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']):

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' }@

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 #}
                 <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                     <b>@{ key }@</b>
-                    {% if value.get('type', None) %}<br/><div style="font-size: small; color: red">@{ value.type }@</div>{% endif %}
+                    <div style="font-size: small">
-                    {% if value.get('required', False) %}<br/><div style="font-size: small; color: red">required</div>{% endif %}
+                        <span style="color: purple">@{ value.type | documented_type }@</span>
-                    {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
+                        {% if value.get('required', False) %} / <span style="color: red">required</span>{% endif %}
+                    </div>
+                    {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %}
                 </td>
                 {# default / choices #}
                 <td>
@@ -135,7 +137,7 @@ Parameters
                     {% endif %}
                     {# Show possible choices and highlight details #}
                     {% if value.choices %}
-                        <ul><b>Choices:</b>
+                        <ul style="margin: 0; padding: 0"><b>Choices:</b>
                             {% 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 %}
                 <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@" colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                     <b>@{ key }@</b>
-                    <br/><div style="font-size: small; color: red">@{ value.type }@</div>
+                    <div style="font-size: small; color: purple">@{ value.type | documented_type }@</div>
-                    {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
+                    {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %}
                 </td>
                 <td>@{ value.returned | html_ify }@</td>
                 <td>
@@ -365,8 +367,8 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
                 {% endfor %}
                 <td colspan="@{ from_kludge_ns('maxdepth') - loop.depth0 }@">
                     <b>@{ key }@</b>
-                    <br/><div style="font-size: small; color: red">@{ value.type }@</div>
+                    <div style="font-size: small; color: purple">@{ value.type | documented_type }@</div>
-                    {% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
+                    {% if value.version_added %}<div style="font-style: italic; font-size: small; color: darkgreen">added in @{value.version_added}@</div>{% endif %}
                 </td>
                 <td>@{ value.returned | html_ify }@</td>
                 <td>
@@ -405,53 +407,46 @@ Common return values are documented :ref:`here <common_return_values>`, 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 <modules_support>` for more info.
+- This @{ plugin_type }@ is :ref:`maintained by @{ supported_by }@ <modules_support>`. *[@{ metadata.supported_by }@]*
-
-For a list of other modules that are also maintained by @{ supported_by }@, see :ref:`here <@{ metadata.supported_by }@_supported>`.
 
 {%       if metadata.supported_by in ('core', 'network') %}
+Red Hat Support
+~~~~~~~~~~~~~~~
 
-Support
+More information about Red Hat's support of this @{ plugin_type }@ is available from this `Red Hat Knowledge Base article <https://access.redhat.com/articles/3166901>`_.
-~~~~~~~
-
-For more information about Red Hat's support of this @{ plugin_type }@,
-please refer to this `Knowledge Base article <https://access.redhat.com/articles/rhel-top-support-policies/>`_
 {%       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 -%}
-
+Authors
-Author
+~~~~~~~
-~~~~~~
 
 {%   for author_name in author %}
 - @{ author_name }@