Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Generate role documentation.
Browse files Browse the repository at this point in the history
felixfontein committed Jun 22, 2021

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 58e6108 commit 582a543
Showing 6 changed files with 445 additions and 17 deletions.
9 changes: 7 additions & 2 deletions antsibull/augment_docs.py
Original file line number Diff line number Diff line change
@@ -56,5 +56,10 @@ def augment_docs(plugin_info: t.MutableMapping[str, t.MutableMapping[str, t.Any]
"""
for plugin_type, plugin_map in plugin_info.items():
for plugin_name, plugin_record in plugin_map.items():
add_full_key(plugin_record['return'], 'contains')
add_full_key(plugin_record['doc']['options'], 'suboptions')
if 'return' in plugin_record:
add_full_key(plugin_record['return'], 'contains')
if 'doc' in plugin_record:
add_full_key(plugin_record['doc']['options'], 'suboptions')
if 'entry_points' in plugin_record:
for entry_point in plugin_record['entry_points'].values():
add_full_key(entry_point['options'], 'suboptions')
9 changes: 7 additions & 2 deletions antsibull/cli/doc_commands/stable.py
Original file line number Diff line number Diff line change
@@ -230,8 +230,13 @@ def get_plugin_contents(plugin_info: t.Mapping[str, t.Mapping[str, t.Any]],
for plugin_type, plugin_list in plugin_info.items():
for plugin_name, plugin_desc in plugin_list.items():
namespace, collection, short_name = get_fqcn_parts(plugin_name)
plugin_contents[plugin_type]['.'.join((namespace, collection))][short_name] = (
plugin_desc['doc']['short_description'])
if plugin_type == 'role':
desc = ''
if 'main' in plugin_desc['entry_points']:
desc = plugin_desc['entry_points']['main']['short_description']
else:
desc = plugin_desc['doc']['short_description']
plugin_contents[plugin_type]['.'.join((namespace, collection))][short_name] = desc

return plugin_contents

3 changes: 3 additions & 0 deletions antsibull/data/docsite/list_of_plugins.rst.j2
Original file line number Diff line number Diff line change
@@ -5,6 +5,9 @@
{% if plugin_type == 'module' %}
Index of all Modules
====================
{% elif plugin_type == 'role' %}
Index of all Roles
==================
{% else %}
Index of all @{ plugin_type | capitalize }@ Plugins
=============@{ '=' * (plugin_type | length) }@========
19 changes: 17 additions & 2 deletions antsibull/data/docsite/plugins_by_collection.rst.j2
Original file line number Diff line number Diff line change
@@ -29,20 +29,35 @@ Collection version @{ collection_version }@

{% endfor %}

{% if 'role' in plugin_maps %}
Role Index
----------

These are the roles in the @{collection_name}@ collection

{% for name, desc in plugin_maps['role'].items() | sort %}
* :ref:`@{ name }@ <ansible_collections.@{ collection_name }@.@{ name }@_role>` -- @{ desc | rst_ify | indent(width=2) }@
{% endfor %}

{% endif %}

Plugin Index
------------

{% if plugin_maps %}
{% if plugin_maps | reject('eq', 'role') | list %}
These are the plugins in the @{collection_name}@ collection
{% else %}
There are no plugins in the @{collection_name}@ collection with automatically generated documentation.
{% endif %}

{% for category, plugins in plugin_maps.items() | sort %}
{% for category, plugins in plugin_maps.items() | sort | rejectattr('0', 'eq', 'role') %}

{% if category == 'module' %}
Modules
~~~~~~~
{% elif category == 'role' %}
Roles
~~~~~
{% else %}
@{ category | capitalize }@ Plugins
@{ '~' * ((category | length) + 8) }@
Loading

0 comments on commit 582a543

Please sign in to comment.