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)
This commit is contained in:
Dag Wieers
Toshio Kuratomi
parent
a22f46bacf
commit
50d06d9889
3 changed files with 56 additions and 53 deletions
|
|
@ -1,22 +1,9 @@
|
|||
#!/usr/bin/env python
|
||||
# (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
|
||||
# (c) 2012-2014, Michael DeHaan <michael@ansible.com> 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 <http://www.gnu.org/licenses/>.
|
||||
# Copyright: (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
|
||||
# Copyright: (c) 2012-2014, Michael DeHaan <michael@ansible.com> 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']):
|
||||
|
|
|
|||
|
|
@ -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' }@
|
||||
|
|
|
|||
61
docs/templates/plugin.rst.j2
vendored
61
docs/templates/plugin.rst.j2
vendored
|
|
@ -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 %}
|
||||
{% if value.get('required', False) %}<br/><div style="font-size: small; color: red">required</div>{% endif %}
|
||||
{% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
|
||||
<div style="font-size: small">
|
||||
<span style="color: purple">@{ value.type | documented_type }@</span>
|
||||
{% 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>
|
||||
{% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
|
||||
<div style="font-size: small; color: purple">@{ value.type | documented_type }@</div>
|
||||
{% 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>
|
||||
{% if value.version_added %}<br/><div style="font-size: small; color: darkgreen">(added in @{value.version_added}@)</div>{% endif %}
|
||||
<div style="font-size: small; color: purple">@{ value.type | documented_type }@</div>
|
||||
{% 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.
|
||||
|
||||
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 }@ <modules_support>`. *[@{ 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 <https://access.redhat.com/articles/rhel-top-support-policies/>`_
|
||||
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>`_.
|
||||
{% 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 }@
|
||||
|
|
|
|||
Loading…
Reference in a new issue