Skip to content

Commit

Permalink
Generate role documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
felixfontein committed May 25, 2021
1 parent be5c276 commit 4b4fb03
Show file tree
Hide file tree
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
Expand Up @@ -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
Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions antsibull/data/docsite/list_of_plugins.rst.j2
Original file line number Diff line number Diff line change
Expand Up @@ -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) }@========
Expand Down
19 changes: 17 additions & 2 deletions antsibull/data/docsite/plugins_by_collection.rst.j2
Original file line number Diff line number Diff line change
Expand Up @@ -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) }@
Expand Down
Loading

0 comments on commit 4b4fb03

Please sign in to comment.