archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

ansible-doc: show 'notes', 'seealso', and top-level 'version_added' for role entrypoints (#81796)

Browse Source 
* Show 'notes', 'seealso', 'requirements', and top-level 'version_added' for role entrypoints.

Co-authored-by: Matt Clay <matt@mystile.com>
pull/81672/merge
Felix Fontein 4 months ago committed by GitHub
parent 15e9f51e2d
commit 45d62a726c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 91 additions and 43 deletions
Show Stats Download Patch File Download Diff File

2
changelogs/fragments/81796-ansible-doc-roles.yml
Unescape Escape View File

@ -0,0 +1,2 @@
minor_changes:
- "ansible-doc - show ``notes``, ``seealso``, and top-level ``version_added`` for role entrypoints (https://github.com/ansible/ansible/pull/81796)."

104
lib/ansible/cli/doc.py
Unescape Escape View File

@ -1344,6 +1344,51 @@ class DocCLI(CLI, RoleMixin):
text.append("%s%s:" % (opt_indent, subkey))
DocCLI.add_fields(text, subdata, limit, opt_indent + ' ', return_values, opt_indent)
@staticmethod
def _add_seealso(text: list[str], seealsos: list[dict[str, t.Any]], limit: int, opt_indent: str) -> None:
for item in seealsos:
if 'module' in item:
text.append(DocCLI.warp_fill(DocCLI.tty_ify('Module %s' % item['module']),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
description = item.get('description')
if description is None and item['module'].startswith('ansible.builtin.'):
description = 'The official documentation on the %s module.' % item['module']
if description is not None:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(description),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
if item['module'].startswith('ansible.builtin.'):
relative_url = 'collections/%s_module.html' % item['module'].replace('.', '/', 2)
text.append(DocCLI.warp_fill(DocCLI.tty_ify(get_versioned_doclink(relative_url)),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent))
elif 'plugin' in item and 'plugin_type' in item:
plugin_suffix = ' plugin' if item['plugin_type'] not in ('module', 'role') else ''
text.append(DocCLI.warp_fill(DocCLI.tty_ify('%s%s %s' % (item['plugin_type'].title(), plugin_suffix, item['plugin'])),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
description = item.get('description')
if description is None and item['plugin'].startswith('ansible.builtin.'):
description = 'The official documentation on the %s %s%s.' % (item['plugin'], item['plugin_type'], plugin_suffix)
if description is not None:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(description),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
if item['plugin'].startswith('ansible.builtin.'):
relative_url = 'collections/%s_%s.html' % (item['plugin'].replace('.', '/', 2), item['plugin_type'])
text.append(DocCLI.warp_fill(DocCLI.tty_ify(get_versioned_doclink(relative_url)),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent))
elif 'name' in item and 'link' in item and 'description' in item:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['name']),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['description']),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['link']),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
elif 'ref' in item and 'description' in item:
text.append(DocCLI.warp_fill(DocCLI.tty_ify('Ansible documentation [%s]' % item['ref']),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['description']),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(get_versioned_doclink('/#stq=%s&stp=1' % item['ref'])),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
def get_role_man_text(self, role, role_json):
"""Generate text for the supplied role suitable for display.
@ -1371,6 +1416,9 @@ class DocCLI(CLI, RoleMixin):
text.append("ENTRY POINT: %s %s" % (_format(entry_point, "BOLD"), desc))
text.append('')
if version_added := doc.pop('version_added', None):
text.append(_format("ADDED IN:", 'bold') + " %s\n" % DocCLI._format_version_added(version_added))
if doc.get('description'):
if isinstance(doc['description'], list):
descs = doc['description']
@ -1401,6 +1449,18 @@ class DocCLI(CLI, RoleMixin):
text.append(DocCLI._indent_lines(DocCLI._dump_yaml(doc['attributes'][k]), opt_indent))
del doc['attributes']
if notes := doc.pop('notes', False):
text.append("")
text.append(_format("NOTES:", 'bold'))
for note in notes:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(note), limit - 6,
initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
if seealso := doc.pop('seealso', False):
text.append("")
text.append(_format("SEE ALSO:", 'bold'))
DocCLI._add_seealso(text, seealso, limit=limit, opt_indent=opt_indent)
# generic elements we will handle identically
for k in ('author',):
if k not in doc:
@ -1497,49 +1557,7 @@ class DocCLI(CLI, RoleMixin):
if doc.get('seealso', False):
text.append("")
text.append(_format("SEE ALSO:", 'bold'))
for item in doc['seealso']:
if 'module' in item:
text.append(DocCLI.warp_fill(DocCLI.tty_ify('Module %s' % item['module']),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
description = item.get('description')
if description is None and item['module'].startswith('ansible.builtin.'):
description = 'The official documentation on the %s module.' % item['module']
if description is not None:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(description),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
if item['module'].startswith('ansible.builtin.'):
relative_url = 'collections/%s_module.html' % item['module'].replace('.', '/', 2)
text.append(DocCLI.warp_fill(DocCLI.tty_ify(get_versioned_doclink(relative_url)),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent))
elif 'plugin' in item and 'plugin_type' in item:
plugin_suffix = ' plugin' if item['plugin_type'] not in ('module', 'role') else ''
text.append(DocCLI.warp_fill(DocCLI.tty_ify('%s%s %s' % (item['plugin_type'].title(), plugin_suffix, item['plugin'])),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
description = item.get('description')
if description is None and item['plugin'].startswith('ansible.builtin.'):
description = 'The official documentation on the %s %s%s.' % (item['plugin'], item['plugin_type'], plugin_suffix)
if description is not None:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(description),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
if item['plugin'].startswith('ansible.builtin.'):
relative_url = 'collections/%s_%s.html' % (item['plugin'].replace('.', '/', 2), item['plugin_type'])
text.append(DocCLI.warp_fill(DocCLI.tty_ify(get_versioned_doclink(relative_url)),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent))
elif 'name' in item and 'link' in item and 'description' in item:
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['name']),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['description']),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['link']),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
elif 'ref' in item and 'description' in item:
text.append(DocCLI.warp_fill(DocCLI.tty_ify('Ansible documentation [%s]' % item['ref']),
limit - 6, initial_indent=opt_indent[:-2] + "* ", subsequent_indent=opt_indent))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(item['description']),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
text.append(DocCLI.warp_fill(DocCLI.tty_ify(get_versioned_doclink('/#stq=%s&stp=1' % item['ref'])),
limit - 6, initial_indent=opt_indent + ' ', subsequent_indent=opt_indent + ' '))
DocCLI._add_seealso(text, doc['seealso'], limit=limit, opt_indent=opt_indent)
del doc['seealso']
if doc.get('requirements', False):

2
test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/roles/testrole/meta/main.yml
Unescape Escape View File

@ -13,6 +13,7 @@ argument_specs:
description: opt1 description
type: "str"
required: true
version_added: 1.2.0
alternate:
short_description: testns.testcol.testrole short description for alternate entry point
@ -23,6 +24,7 @@ argument_specs:
check_mode:
description: Can run in check_mode and return changed status prediction without modifying target
support: full
version_added: 2.1.0
options:
altopt1:
description: altopt1 description

2
test/integration/targets/ansible-doc/fakecollrole.output
Unescape Escape View File

@ -2,6 +2,8 @@
ENTRY POINT: *alternate* - testns.testcol.testrole short description for alternate entry point
ADDED IN: version 2.1.0
Longer description for testns.testcol.testrole alternate
entry point.

15
test/integration/targets/ansible-doc/fakerole.output
Unescape Escape View File

@ -2,6 +2,8 @@
ENTRY POINT: *main* - test_role1 from roles subdir
ADDED IN: version 1.2.0
In to am attended desirous raptures *declared* diverted
confined at. Collected instantly remaining up certainly to
`necessary' as. Over walk dull into son boy door went new.
@ -33,4 +35,17 @@ ATTRIBUTES:
details: Not all modules used support this
support: partial
NOTES:
* This is a role.
* More text.
SEE ALSO:
* Module ansible.builtin.file
The official documentation on the
ansible.builtin.file module.
https://docs.ansible.com/ansible-core/devel/collections/ansible/builtin/file_module.html
* Lookup plugin ansible.builtin.file
Reads a file from the controller.
https://docs.ansible.com/ansible-core/devel/collections/ansible/builtin/file_lookup.html
AUTHOR: John Doe (@john), Jane Doe (@jane)

9
test/integration/targets/ansible-doc/roles/test_role1/meta/argument_specs.yml
Unescape Escape View File

@ -16,6 +16,15 @@ argument_specs:
description: Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
support: partial
details: Not all modules used support this
version_added: 1.2.0
notes:
- This is a role.
- More text.
seealso:
- module: ansible.builtin.file
- plugin: ansible.builtin.file
plugin_type: lookup
description: Reads a file from the controller.
options:
myopt1:
description:

Write Preview
Loading…
Cancel
Save