mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-07 05:42:50 +00:00
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
committed by
Alicia Cozine
Alicia Cozine
parent
6b09e99664
commit
baf0ad2309
@@ -1,17 +1,5 @@
|
||||
# (c) 2014, James Tanner <tanner.jc@gmail.com>
|
||||
#
|
||||
# Ansible is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# Ansible is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
# Copyright: (c) 2014, James Tanner <tanner.jc@gmail.com>
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
from __future__ import (absolute_import, division, print_function)
|
||||
__metaclass__ = type
|
||||
@@ -573,8 +561,45 @@ class DocCLI(CLI):
|
||||
for note in doc['notes']:
|
||||
text.append(textwrap.fill(CLI.tty_ify(note), limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
|
||||
text.append('')
|
||||
text.append('')
|
||||
del doc['notes']
|
||||
|
||||
if 'seealso' in doc and doc['seealso']:
|
||||
text.append("SEE ALSO:")
|
||||
for item in doc['seealso']:
|
||||
if 'module' in item and 'description' in item:
|
||||
text.append(textwrap.fill(CLI.tty_ify('Module %s' % item['module']),
|
||||
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
|
||||
text.append(textwrap.fill(CLI.tty_ify(item['description']),
|
||||
limit - 6, initial_indent=opt_indent, subsequent_indent=opt_indent))
|
||||
text.append(textwrap.fill(CLI.tty_ify('https://docs.ansible.com/ansible/latest/modules/%s_module.html' % item['module']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent))
|
||||
elif 'module' in item:
|
||||
text.append(textwrap.fill(CLI.tty_ify('Module %s' % item['module']),
|
||||
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
|
||||
text.append(textwrap.fill(CLI.tty_ify('The official documentation on the %s module.' % item['module']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
|
||||
text.append(textwrap.fill(CLI.tty_ify('https://docs.ansible.com/ansible/latest/modules/%s_module.html' % item['module']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent))
|
||||
elif 'name' in item and 'link' in item and 'description' in item:
|
||||
text.append(textwrap.fill(CLI.tty_ify(item['name']),
|
||||
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
|
||||
text.append(textwrap.fill(CLI.tty_ify(item['description']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
|
||||
text.append(textwrap.fill(CLI.tty_ify(item['link']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
|
||||
elif 'ref' in item and 'description' in item:
|
||||
text.append(textwrap.fill(CLI.tty_ify('Ansible documentation [%s]' % item['ref']),
|
||||
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
|
||||
text.append(textwrap.fill(CLI.tty_ify(item['description']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
|
||||
text.append(textwrap.fill(CLI.tty_ify('https://docs.ansible.com/ansible/latest/#stq=%s&stp=1' % item['ref']),
|
||||
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
|
||||
|
||||
text.append('')
|
||||
text.append('')
|
||||
del doc['seealso']
|
||||
|
||||
if 'requirements' in doc and doc['requirements'] is not None and len(doc['requirements']) > 0:
|
||||
req = ", ".join(doc.pop('requirements'))
|
||||
text.append("REQUIREMENTS:%s\n" % textwrap.fill(CLI.tty_ify(req), limit - 16, initial_indent=" ", subsequent_indent=opt_indent))
|
||||
@@ -594,14 +619,16 @@ class DocCLI(CLI):
|
||||
|
||||
if 'plainexamples' in doc and doc['plainexamples'] is not None:
|
||||
text.append("EXAMPLES:")
|
||||
text.append('')
|
||||
if isinstance(doc['plainexamples'], string_types):
|
||||
text.append(doc.pop('plainexamples').strip())
|
||||
else:
|
||||
text.append(yaml.dump(doc.pop('plainexamples'), indent=2, default_flow_style=False))
|
||||
text.append('')
|
||||
text.append('')
|
||||
|
||||
if 'returndocs' in doc and doc['returndocs'] is not None:
|
||||
text.append("RETURN VALUES:\n")
|
||||
text.append("RETURN VALUES:")
|
||||
if isinstance(doc['returndocs'], string_types):
|
||||
text.append(doc.pop('returndocs'))
|
||||
else:
|
||||
|
||||
Reference in New Issue
Block a user