Docs: Add a "seealso" section to the module docs

[dagwieers]

SUMMARY

Something I wanted for a longer time was a separate section 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)

ISSUE TYPE

• Docs Pull Request
• Feature Pull Request

COMPONENT NAME

Module docs

ANSIBLE VERSION

v2.8

ADDITIONAL INFORMATION

Before:

After:

ansible-doc output

SEE ALSO:
      * Module aci_bd
           The official documentation on the aci_bd module.
           https://docs.ansible.com/ansible/devel/modules/aci_bd_module.html
      * Module aci_tenant
           The official documentation on the aci_tenant module.
           https://docs.ansible.com/ansible/devel/modules/aci_tenant_module.html
      * Ansible documentation [aci_guide]
           Detailed information on how to manage your ACI infrastructure using Ansible.
           https://docs.ansible.com/ansible/latest/#stq=aci_guide&stp=1
      * Ansible documentation [aci_dev_guide]
           Detailed guide on how to write your own Cisco ACI modules to contribute.
           https://docs.ansible.com/ansible/latest/#stq=aci_dev_guide&stp=1

The documentation for this feature looks like this:

TODO (see #45985):

• Currently ref-type references cannot be converted to a title + link, as Sphinx takes care of this internally. The solution is to make a searchable link that brings the user to the document based on the reference name.

[ansibot]

cc @acozine @brunocalogero @jmcgill298 @schunduri
click here for bot help

[dagwieers]

cc @felixfontein

[ansibot]

cc @gundalow @mattclay @sivel
click here for bot help

[gundalow]

This looks like a good addition. We will review in more detail after AnsibleFest

schema.py and /developing_modules_documenting will also need updating

Added to https://etherpad.openstack.org/p/ansible-summit-october-2018-documentation

[gundalow]

Dag, good point. Let's stick with /latest/

[dagwieers]

Ok, so anything else needed before we can merge this ?

[acozine]

@dagwieers could the seealso section use the existing, documented link syntax to link to URLs and module docs? (U(https:external_url) for links and M(module_name) for modules)

[dagwieers]

@acozine It is a YAML dictionary, not a free text-field. Because we don't let the user do the markup, it is a listing of information we present depending on where it is being used. So it doesn't make sense.

For instance, for the module entry we depend on the Sphinx references to automatically fill in the title.

[dagwieers]

@acozine @gundalow I would like to implement seealso: now for the windows/python modules that relate to each other (we now use notes) and for the modules that relate to each other (typically copy + template, copy + rsync, command + shell + raw +script, etc...) and for the ACI modules.

We probably want to communicate this to other authors too.