{% from 'macros/parameters.rst.j2' import in_rst as parameters_rst with context %}
{% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %}
.. Document meta

:orphan:
{% if edit_on_github_url %}
:github_url: @{ edit_on_github_url }@?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr
{% endif %}

.. role:: ansible-option-type
.. role:: ansible-option-elements
.. role:: ansible-option-required
.. role:: ansible-option-versionadded
.. role:: ansible-option-aliases
.. role:: ansible-option-choices
.. role:: ansible-option-choices-entry
.. role:: ansible-option-default
.. role:: ansible-option-default-bold

{# If we can put together source and github repo, we could make the Edit me of github button work.
   See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html
   for more information
:source: @{ source }@
-#}

.. Anchors

.. _ansible_collections.@{plugin_name}@_@{plugin_type}@:

.. Anchors: aliases

{# TODO: This assumes that aliases will be short names.
   If they're FQCN, then we need to change this
#}

.. Title

{% if entry_points.main and entry_points.main.short_description -%}
{%   set title = plugin_name ~ ' ' ~ plugin_type ~ ' -- ' ~ entry_points.main.short_description | rst_ify -%}
{% else -%}
{%   set title = plugin_name ~ ' ' ~ plugin_type -%}
{% endif -%}

@{ title }@
@{ '+' * title|length }@

.. Collection note

{% if collection == 'ansible.builtin' -%}
.. note::
    This role is part of ``ansible-core`` and included in all Ansible
    installations.
{% else %}
.. note::
    This role is part of the `@{collection}@ collection <https://galaxy.ansible.com/@{collection | replace('.', '/', 1)}@>`_{% if collection_version %} (version @{ collection_version }@){% endif %}.

    To install it use: :code:`ansible-galaxy collection install @{collection}@`.

    To use it in a playbook, specify: :code:`@{plugin_name}@`.
{% endif %}

.. contents::
   :local:
   :depth: 2

{% for entry_point, ep_doc in entry_points.items() | sort %}

.. Entry point title

{%   if ep_doc['short_description'] -%}
{%     set title = 'Entry point ``' + entry_point + '`` -- ' + ep_doc['short_description'] | rst_ify -%}
{%   else -%}
{%     set title = 'Entry point ``' + entry_point + '``' -%}
{%   endif -%}

@{ title }@
@{ '-' * title|length }@

.. version_added

{%   if ep_doc['version_added'] is still_relevant(collection=collection) -%}
.. versionadded:: @{ ep_doc['version_added'] }@ of @{ collection | rst_ify }@
{%   endif %}

.. Deprecated

{%   if ep_doc['deprecated'] -%}
DEPRECATED
^^^^^^^^^^
{%     if ep_doc['deprecated']['removed_at_date'] %}
:Removed in: major release after @{ ep_doc['deprecated']['removed_at_date'] | rst_ify }@
{%     elif ep_doc['deprecated']['removed_in'] %}
:Removed in: version @{ ep_doc['deprecated']['removed_in'] | rst_ify }@
{%     else %}
:Removed in: a future release
{%     endif %}
:Why: @{ ep_doc['deprecated']['why'] | rst_ify }@
:Alternative: @{ ep_doc['deprecated']['alternative'] | rst_ify }@
{%   endif %}

Synopsis
^^^^^^^^

.. Description

{%   for desc in ep_doc['description'] -%}
- @{ desc | rst_ify | indent(width=2) }@
{%   endfor %}

.. Requirements

{%   if ep_doc['requirements'] -%}
Requirements
^^^^^^^^^^^^
The below requirements are needed on the remote host and/or the local controller node.

{%     for req in ep_doc['requirements'] %}
- @{ req | rst_ify | indent(width=2) }@
{%     endfor %}

{%   endif %}

.. Options

{%   if ep_doc['options'] -%}

Parameters
^^^^^^^^^^

{%     if use_html_blobs %}
@{       parameters_html(ep_doc['options'], suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__') }@
{%     else %}
@{       parameters_rst(ep_doc['options'], suboption_key='options', parameter_html_prefix=entry_point ~ '--', parameter_rst_prefix=entry_point ~ '__') }@
{%     endif %}
{%   endif %}

.. Notes

{%   if ep_doc['notes'] -%}
Notes
^^^^^

.. note::
{%     for note in ep_doc['notes'] %}
   - @{ note | rst_ify | indent(width=5) }@
{%     endfor %}
{%   endif %}

.. Seealso

{%   if ep_doc['seealso'] -%}
See Also
^^^^^^^^

.. seealso::

{%     for item in ep_doc['seealso'] %}
{%       if item.module is defined and item.description %}
   @{ ('M(' + item['module'] + ')') | rst_ify }@
       @{ item['description'] | rst_ify }@
{%       elif item.module is defined %}
   @{ ('M(' + item['module'] + ')') | rst_ify }@
      The official documentation on the **@{ item['module'] }@** module.
{%       elif item.name is defined and item.link is defined and item.description %}
   `@{ item['name'] }@ <@{ item['link'] }@>`_
       @{ item['description'] | rst_ify }@
{%       elif item.ref is defined and item.description %}
   :ref:`@{ item['ref'] }@`
       @{ item['description'] | rst_ify }@
{%       endif %}
{%     endfor %}
{%   endif %}

{%   if ep_doc['author'] -%}
Authors
^^^^^^^

{%     for author_name in ep_doc['author'] %}
- @{ author_name | massage_author_name }@
{%     endfor %}

{%   endif %}

{% endfor %}

.. Extra links

{% if collection_links or not collection_communication.empty %}
Collection links
~~~~~~~~~~~~~~~~

.. raw:: html

  <p class="ansible-links">
{%   for link in collection_links %}
    <a href="@{ link.url | escape }@" aria-role="button" target="_blank" rel="noopener external">@{ link.description | escape }@</a>
{%   endfor %}
{%   if not collection_communication.empty %}
{#     WARNING: the anchor is created from Sphinx from the label and might change #}
    <a href="./#communication-for-@{ collection | replace('.', '-') | escape }@" aria-role="button" target="_blank">Communication</a>
{%   endif %}
  </p>
{% endif %}

.. Parsing errors

{% if nonfatal_errors %}
There were some errors parsing the documentation for this role.  Please file a bug with the collection.

The errors were:

{% for error in nonfatal_errors %}
* ::

@{ error | indent(width=8, first=True) }@

{% endfor %}
{% endif %}
