diff options
| -rw-r--r-- | docs/docsite/_themes/sphinx_rtd_theme/footer.html | 4 | ||||
| -rw-r--r-- | docs/templates/plugin.rst.j2 | 192 |
2 files changed, 131 insertions, 65 deletions
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 @@ </script> <p> + {%- if last_updated %}{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>{% endif %} Copyright © 2018 Red Hat, Inc. <br/> - {%- if last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} - {%- endif %} </p> </footer> 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 </br> {% 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 %} +{% endif %} -{% if returndocs -%} +{% 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 returnfacts -%} -Return Values -------------- - -Common return values are documented :ref:`here <common_return_values>`, 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 <table border=0 cellpadding=0 class="documentation-table"> <tr> - <th class="head"><div class="cell-border">Name</div></th> - <th class="head"><div class="cell-border">Description</div></th> + <th class="head"><div class="cell-border">Fact</div></th> <th class="head"><div class="cell-border">Returned</div></th> - <th class="head"><div class="cell-border">Type</div></th> - <th class="head"><div class="cell-border">Sample</div></th> + <th class="head"><div class="cell-border">Description</div></th> </tr> - {% for key, value in returndocs|dictsort recursive %} + {% for key, value in returnfacts|dictsort recursive %} <tr class="return-value-column"> <td> <div class="outer-elbow-container"> @@ -243,21 +236,28 @@ Common return values are documented :ref:`here <common_return_values>`, the foll {% endfor %} <div class="elbow-key"> <b>@{ key }@</b> + <br/><div style="font-size: small; color: red">@{ value.type }@</div> </div> </div> </td> + <td><div class="cell-border">@{ value.returned }@</div></td> <td> - {% if value.description is string %} - <div class="cell-border">@{ value.description | replace('\n', '\n ') | html_ify }@</div> - {% else %} - {% for desc in value.description %} - <div class="cell-border">@{ desc | replace('\n', '\n ') | html_ify }@</div> - {% endfor %} - {% endif %} + <div class="cell-border"> + {% if value.description is string %} + <div>@{ value.description | html_ify }@</div> + {% else %} + {% for desc in value.description %} + <div>@{ desc | html_ify }@</div> + {% endfor %} + {% endif %} + <br/> + {% if value.sample %} + <div style="font-size: smaller"><b>Sample:</b></div> +{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #} + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> + {% endif %} + </div> </td> - <td><div class="cell-border">@{ value.returned }@</div></td> - <td><div class="cell-border">@{ value.type }@</div></td> - <td><div class="cell-border">@{ value.sample | replace('\n', '\n ') | html_ify }@</div></td> </tr> {# --------------------------------------------------------- # sadly we cannot blindly iterate through the child dicts, @@ -273,49 +273,117 @@ Common return values are documented :ref:`here <common_return_values>`, the foll {% endif %} {% endfor %} </table> - </br></br> -{% endif %} + <br/><br/> +{% endif %} -{% if author is defined -%} - +{% if returndocs -%} -Author -~~~~~~ +Return Values +------------- +Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this @{ plugin_type }@: -{% for author_name in author %} -* @{ author_name }@ -{% endfor %} +.. raw:: html + <table border=0 cellpadding=0 class="documentation-table"> + <tr> + <th class="head"><div class="cell-border">Key</div></th> + <th class="head"><div class="cell-border">Returned</div></th> + <th class="head"><div class="cell-border">Description</div></th> + </tr> + {% for key, value in returndocs|dictsort recursive %} + <tr class="return-value-column"> + <td> + <div class="outer-elbow-container"> + {% for i in range(1, loop.depth) %} + <div class="elbow-placeholder"> + </div> + {% endfor %} + <div class="elbow-key"> + <b>@{ key }@</b> + <br/><div style="font-size: small; color: red">@{ value.type }@</div> + </div> + </div> + </td> + <td><div class="cell-border">@{ value.returned }@</div></td> + <td> + <div class="cell-border"> + {% if value.description is string %} + <div>@{ value.description | html_ify }@</div> + {% else %} + {% for desc in value.description %} + <div>@{ desc | html_ify }@</div> + {% endfor %} + {% endif %} + <br/> + {% if value.sample %} + <div style="font-size: smaller"><b>Sample:</b></div> +{# <div style="font-size: smaller; color: blue; word-wrap: break-word; overflow-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> #} + <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">@{ value.sample | html_ify }@</div> + {% endif %} + </div> + </td> + </tr> + {# --------------------------------------------------------- + # 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 %} + </table> + <br/><br/> {% 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 %} - -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 -~~~~~~~~~~~~~~~~ +{% if metadata.supported_by in ('core', 'network') %} +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/>`_ {% 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 author is defined -%} + +Author +~~~~~~ + +{% for author_name in author %} +- @{ author_name }@ +{% endfor %} + {% endif %} -If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A+label:%20docsite_pr>`_ to improve it. +.. hint:: + If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A+label:%20docsite_pr>`_ to improve it. |