Docs: Add a "seealso" section to the module docs (#45949)

* Docs: Add a separate  "seealso" section to the module docs
to list related modules and/or related references. This clears up the notes
section for things that are actual notes.

So you can add a section in your module documentation and four types of
references are possible.

    seealso:

    # Reference by module name
    - module: aci_tenant

    # Reference by module name, including description
    - module: aci_tenant
      description: ACI module to create tenants on a Cisco ACI fabric.

    # Reference by rST documentation anchor
    - ref: aci_guide
      description: Detailed information on how to manage your ACI infrastructure using Ansible.

    # Reference by Internet resource
    - name: APIC Management Information Model reference
      description: Complete reference of the APIC object model.
      link: https://developer.cisco.com/docs/apic-mim-ref/

This PR also includes:

- Implements ansible-doc support
- Implements schema support for the seealso options
- Updates to the development documentation
- Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters
  - This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again).
- We fixed the possible suboption types (which was limited to 'bool' only)

* Use latest stable instead of devel docs

1 files changed, 33 insertions, 10 deletions

diff --git a/docs/templates/plugin.rst.j2 b/docs/templates/plugin.rst.j2
index 095b9aa346..7e971a4c6a 100644
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -11,7 +11,7 @@
 {% endfor %}
 
 {% if short_description %}
-{%   set title = module + ' - ' + short_description|convert_symbols_to_format %}
+{%   set title = module + ' - ' + short_description | rst_ify %}
 {% else %}
 {%   set title = module %}
 {% endif %}
@@ -39,9 +39,9 @@
 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 }@
-:Alternative: @{ deprecated['alternative'] | default('')|  convert_symbols_to_format }@
+:Removed in Ansible: version: @{ deprecated['removed_in'] | default('') | string | rst_ify }@
+:Why: @{ deprecated['why'] | default('') | rst_ify }@
+:Alternative: @{ deprecated['alternative'] | default('') | rst_ify }@
 
 
 {% endif %}
@@ -51,10 +51,10 @@ Synopsis
 {% if description -%}
 
 {%   if description is string -%}
-- @{ description | convert_symbols_to_format }@
+- @{ description | rst_ify }@
 {%   else %}
 {%     for desc in description %}
-- @{ desc | convert_symbols_to_format }@
+- @{ desc | rst_ify }@
 {%     endfor %}
 {%   endif %}
 
@@ -75,7 +75,7 @@ The below requirements are needed on the local master node that executes this @{
 {%   endif %}
 
 {%   for req in requirements %}
-- @{ req | convert_symbols_to_format }@
+- @{ req | rst_ify }@
 {%   endfor %}
 
 {% endif %}
@@ -206,17 +206,40 @@ Parameters
 {% endif %}
 
 {% if notes -%}
-
 Notes
 -----
 
 .. note::
 {%   for note in notes %}
-    - @{ note | convert_symbols_to_format }@
+   - @{ note | rst_ify }@
 {%   endfor %}
 
 {% endif %}
 
+{% if seealso -%}
+See Also
+--------
+
+.. seealso::
+
+{% for item in seealso %}
+{%   if item.module is defined and item.description is defined %}
+   :ref:`Module @{ item.module }@ <@{ item.module }@_module>`
+       @{ item.description | rst_ify }@
+{%   elif item.module is defined %}
+   :ref:`@{ item.module }@_module`
+      The official documentation on the **@{ item.module }@** module.
+{%   elif item.name is defined and item.link is defined and item.description is defined %}
+   `@{ item.name }@ <@{ item.link }@>`_
+       @{ item.description | rst_ify }@
+{%   elif item.ref is defined and item.description is defined %}
+   :ref:`@{ item.ref }@`
+       @{ item.description | rst_ify }@
+{%   endif %}
+{% endfor %}
+
+{% endif %}
+
 {% if examples or plainexamples -%}
 
 Examples
@@ -421,7 +444,7 @@ please refer to this `Knowledge Base article <https://access.redhat.com/articles
 
 {% else %}
 
-This @{ plugin_type }@ is flagged as **deprecated** and will be removed in version @{ deprecated['removed_in'] | default('') | string | convert_symbols_to_format }@. For more information see `DEPRECATED`_.
+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 %}