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
This commit is contained in:
Dag Wieers 2018-12-12 21:19:58 +01:00 committed by Alicia Cozine
commit baf0ad2309
9 changed files with 153 additions and 52 deletions

View file

@ -2,7 +2,6 @@
# Copyright: (c) 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
# Copyright: (c) 2017, Swetha Chunduri (@schunduri)
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
@ -70,6 +69,9 @@ options:
- This should only set to C(no) when used on personally controlled sites using self-signed certificates.
type: bool
default: 'yes'
notes:
- Please read the :ref:`aci_guide` for more detailed information on how to manage your ACI infrastructure using Ansible.
seealso:
- ref: aci_guide
description: Detailed information on how to manage your ACI infrastructure using Ansible.
- ref: aci_dev_guide
description: Detailed guide on how to write your own Cisco ACI modules to contribute.
'''