diff --git a/docs/docsite/_themes/sphinx_rtd_theme/footer.html b/docs/docsite/_themes/sphinx_rtd_theme/footer.html index 1d8b4278cf..2aa10fe780 100644 --- a/docs/docsite/_themes/sphinx_rtd_theme/footer.html +++ b/docs/docsite/_themes/sphinx_rtd_theme/footer.html @@ -22,9 +22,7 @@

+ {%- if last_updated %}{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
{% endif %} Copyright © 2018 Red Hat, Inc.
- {%- if last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} - {%- endif %}

diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2 index e3c07604d6..9dba81f95e 100644 --- a/docs/templates/plugin.rst.j2 +++ b/docs/templates/plugin.rst.j2 @@ -13,11 +13,8 @@ {% if version_added is defined and version_added != '' -%} .. versionadded:: @{ version_added | default('') }@ - - {% endif %} - .. contents:: :local: :depth: 2 @@ -33,7 +30,6 @@ DEPRECATED ---------- - {# use unknown here? skip the fields? #} :Removed in Ansible: version: @{ deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@ :Why: @{ deprecated['why'] | default('') | convert_symbols_to_format }@ @@ -44,43 +40,40 @@ DEPRECATED Synopsis -------- - -{% if description %} +{% if description -%} {% if description is string -%} -* @{ description | convert_symbols_to_format }@ +- @{ description | convert_symbols_to_format }@ {% else %} -{% for desc in description -%} -* @{ desc | convert_symbols_to_format }@ +{% for desc in description %} +- @{ desc | convert_symbols_to_format }@ {% endfor %} {% endif %} {% endif %} {% if aliases is defined -%} - Aliases: @{ ','.join(aliases) }@ - - {% endif %} -{% if requirements %} -{% set req_title = 'Requirements' %} +{% if requirements -%} + +Requirements +~~~~~~~~~~~~ {% if plugin_type == 'module' %} -{% set req_title = req_title + ' (on host that executes module)' %} +The below requirements are needed on the host that executes this @{ plugin_type }@. +{% else %} +The below requirements are needed on the local master node that executes this @{ plugin_type }@. {% endif %} -@{ req_title }@ -@{ '-' * req_title|length }@ {% for req in requirements %} -* @{ req | convert_symbols_to_format }@ +- @{ req | convert_symbols_to_format }@ {% endfor %} {% endif %} {% if options -%} - Options ------- @@ -186,8 +179,8 @@ Options
{% endif %} -{% if notes -%} +{% if notes -%} Notes ----- @@ -197,10 +190,9 @@ Notes - @{ note | convert_symbols_to_format }@ {% endfor %} - {% endif %} -{% if examples or plainexamples -%} +{% if examples or plainexamples -%} Examples -------- @@ -212,28 +204,29 @@ Examples @{ example['code'] | escape | indent(4, True) }@ {% endfor %} {% if plainexamples %}@{ plainexamples | indent(4, True) }@{% endif %} + {% endif %} +{% if not returnfacts and returndocs and returndocs.ansible_facts is defined %} +{% set returnfacts = returndocs.ansible_facts.contains %} +{% set _x = returndocs.pop('ansible_facts', None) %} +{% endif %} -{% if returndocs -%} +{% if returnfacts -%} - -Return Values -------------- - -Common return values are documented :ref:`here `, the following are the fields unique to this @{ plugin_type }@: +Returned Facts +-------------- +Facts returned by this module are added/updated in the ``hostvars`` host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them. .. raw:: html - - + - - + - {% for key, value in returndocs|dictsort recursive %} + {% for key, value in returnfacts|dictsort recursive %} - - - + {# --------------------------------------------------------- # sadly we cannot blindly iterate through the child dicts, @@ -273,49 +273,117 @@ Common return values are documented :ref:`here `, the foll {% endif %} {% endfor %}
Name
Description
Fact
Returned
Type
Sample
Description
@@ -243,21 +236,28 @@ Common return values are documented :ref:`here `, the foll {% endfor %}
@{ key }@ +
@{ value.type }@
 - {% if value.description is string %} -
@{ value.description | replace('\n', '\n ') | html_ify }@
- {% else %} - {% for desc in value.description %} -
@{ desc | replace('\n', '\n ') | html_ify }@
- {% endfor %} - {% endif %} -
@{ value.returned }@
@{ value.type }@
@{ value.sample | replace('\n', '\n ') | html_ify }@
 +
+ {% if value.description is string %} +
@{ value.description | html_ify }@
+ {% else %} + {% for desc in value.description %} +
@{ desc | html_ify }@
+ {% endfor %} + {% endif %} +
+ {% if value.sample %} +
Sample:
+{#
@{ value.sample | html_ify }@
#} +
@{ value.sample | html_ify }@
+ {% endif %} +
+
-

-{% endif %} - - -{% if author is defined -%} - - -Author -~~~~~~ - -{% for author_name in author %} -* @{ author_name }@ -{% endfor %} - +

{% endif %} -{% if not deprecated %} -{% 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'} %} -{% if metadata %} -{% if metadata.status %} +{% if returndocs -%} + +Return Values +------------- +Common return values are documented :ref:`here `, the following are the fields unique to this @{ plugin_type }@: + +.. raw:: html + + + + + + + + {% for key, value in returndocs|dictsort recursive %} + + + + + + {# --------------------------------------------------------- + # sadly we cannot blindly iterate through the child dicts, + # since in some documentations, + # lists are used instead of dicts. This handles both types + # ---------------------------------------------------------#} + {% if value.contains %} + {% if value.contains.items %} + @{ loop(value.contains.items()) }@ + {% elif value.contains[0].items %} + @{ loop(value.contains[0].items()) }@ + {% endif %} + {% endif %} + {% endfor %} +
Key
Returned
Description
+
+ {% for i in range(1, loop.depth) %} +
+
+ {% endfor %} +
+ @{ key }@ +
@{ value.type }@
+
+
+
@{ value.returned }@
 +
+ {% if value.description is string %} +
@{ value.description | html_ify }@
+ {% else %} + {% for desc in value.description %} +
@{ desc | html_ify }@
+ {% endfor %} + {% endif %} +
+ {% if value.sample %} +
Sample:
+{#
@{ value.sample | html_ify }@
#} +
@{ value.sample | html_ify }@
+ {% endif %} +
+
+

+ +{% endif %} Status -~~~~~~ +------ +{% if not deprecated %} + +{% 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'} %} + +{% if metadata %} +{% if metadata.status %} {% for cur_state in metadata.status %} This module is flagged as **@{cur_state}@** which means that @{module_states[cur_state]}@. {% endfor %} - {% endif %} + {% if metadata.supported_by in ('core', 'network') %} - -Maintenance Info -~~~~~~~~~~~~~~~~ - +Support +~~~~~~~ For more information about Red Hat's support of this @{ plugin_type }@, please refer to this `Knowledge Base article `_ {% endif %} {% endif %} + +{% else %} + +This module is flagged as **deprecated** and will be removed in version { deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@. For more information see :ref:`DEPRECATED`. + {% endif %} -If you notice any issues in this documentation you can `edit this document `_ to improve it. +{% if author is defined -%} + +Author +~~~~~~ + +{% for author_name in author %} +- @{ author_name }@ +{% endfor %} + +{% endif %} + +.. hint:: + If you notice any issues in this documentation you can `edit this document `_ to improve it.