mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-07 22:02:50 +00:00
Generate plugin rst (#28901)
Generate rst docs for plugins Based on rst generated for modules. But generated plugin docs go into docs/docsite/rst/plugins/$PLUGIN_TYPE/plugin_name.rst ( docs/docsite/rst/plugins/connection/ssh.py for ex) * move plugins docs to rst/*_plugins/ subdirs for namespace * Only gen support pages for modules for now. * Add generated plugin docs to gitignore* add list_*_plugins templates * support MODULES/PLUGINS filters for make htmldocs Add a 'PLUGINS=ssh' filter env var like MODULES to filter plugins to build docs for. * fixup 'historical' version_added, skip plugins/loader.py * Fix plugins_by_support ref link to new plugins/*/ location * use :ref: for common_return_values, allow empty version_added * warnings on missing doc info * add a prefix to _random_choice It was colliding with the target for random_choice plugin
This commit is contained in:
Adrian Likins
GitHub
@@ -1,4 +1,4 @@
|
||||
@{ title }@ Modules
|
||||
@{ title }@ @{ plugin_type }@
|
||||
@{ '`' * title | length }@````````
|
||||
|
||||
{% if blurb %}
|
||||
@@ -20,7 +20,8 @@
|
||||
.. toctree:: :maxdepth: 1
|
||||
|
||||
{% for module in info['_modules'] | sort %}
|
||||
@{ module }@{% if module_info[module]['deprecated'] %} **(D)**{% endif%} - @{ module_info[module]['doc']['short_description'] }@ <@{ module }@_module>
|
||||
{# :ref:`@{ module }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} @{ module_info[module]['doc']['short_description'] }@ #}
|
||||
@{ module }@{% if module_info[module]['deprecated'] %} **(D)**{% endif%} @{ module_info[module]['doc']['short_description'] }@ <@{ module }@_module>
|
||||
{% endfor %}
|
||||
|
||||
{% endfor %}
|
||||
|
||||
31
docs/templates/list_of_CATEGORY_plugins.rst.j2
vendored
Normal file
31
docs/templates/list_of_CATEGORY_plugins.rst.j2
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
@{ title }@ @{ plugin_type }@
|
||||
@{ '`' * title | length }@````````
|
||||
|
||||
{% if blurb %}
|
||||
@{ blurb }@
|
||||
|
||||
{% endif %}
|
||||
.. toctree:: :maxdepth: 1
|
||||
{% if category['_modules'] %}
|
||||
|
||||
{% for module in category['_modules'] | sort %}
|
||||
@{ module }@{% if module_info[module]['deprecated'] %} **(D)**{% endif%}{% if module_info[module]['doc']['short_description'] %} - @{ module_info[module]['doc']['short_description'] }@{% endif %} <plugins/@{ module_info[module]['primary_category'] }@/@{ module }@>
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
{% for name, info in subcategories.items() | sort %}
|
||||
@{ name.title() }@
|
||||
@{ '-' * name | length }@
|
||||
|
||||
.. toctree:: :maxdepth: 1
|
||||
|
||||
{% for module in info['_modules'] | sort %}
|
||||
:ref:`@{ module }@`{% if module_info[module]['deprecated'] %} **(D)**{% endif%} @{ module_info[module]['doc']['short_description'] }@
|
||||
{% endfor %}
|
||||
|
||||
{% endfor %}
|
||||
|
||||
.. note::
|
||||
- **(D)**: This marks a module as deprecated, which means a module is kept for backwards compatibility but usage is discouraged.
|
||||
The module documentation details page may explain more about this rationale.
|
||||
|
||||
69
docs/templates/plugin.rst.j2
vendored
69
docs/templates/plugin.rst.j2
vendored
@@ -10,8 +10,10 @@
|
||||
@{ title }@
|
||||
@{ '+' * title_len }@
|
||||
|
||||
{% if version_added is defined -%}
|
||||
.. versionadded:: @{ version_added }@
|
||||
{% if version_added is defined and version_added != '' -%}
|
||||
.. versionadded:: @{ version_added | default('') }@
|
||||
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
@@ -25,36 +27,54 @@
|
||||
# but it isn't one.
|
||||
#
|
||||
--------------------------------------------#}
|
||||
|
||||
{% if deprecated is defined -%}
|
||||
|
||||
|
||||
DEPRECATED
|
||||
----------
|
||||
|
||||
@{ deprecated | convert_symbols_to_format }@
|
||||
{# use unknown here? skip the fields? #}
|
||||
:In: version: @{ deprecated['version'] | default('') | string | convert_symbols_to_format }@
|
||||
:Why: @{ deprecated['why'] | default('') | convert_symbols_to_format }@
|
||||
:Alternative: @{ deprecated['alternative'] | default('')| convert_symbols_to_format }@
|
||||
|
||||
|
||||
{% endif %}
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
{% if description %}
|
||||
|
||||
{% for desc in description -%}
|
||||
* @{ desc | convert_symbols_to_format }@
|
||||
* @{ desc | convert_symbols_to_format }@
|
||||
{% endfor %}
|
||||
|
||||
{% if aliases is defined -%}
|
||||
Aliases: @{ ','.join(aliases) }@
|
||||
{% endif %}
|
||||
|
||||
{% endif %}
|
||||
{% if aliases is defined -%}
|
||||
|
||||
Aliases: @{ ','.join(aliases) }@
|
||||
|
||||
|
||||
{% endif %}
|
||||
{% if requirements %}
|
||||
|
||||
Requirements (on host that executes module)
|
||||
-------------------------------------------
|
||||
|
||||
{% if requirements %}
|
||||
{% for req in requirements %}
|
||||
* @{ req | convert_symbols_to_format }@
|
||||
{% endfor %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% endif %}
|
||||
{% if options -%}
|
||||
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
@@ -161,9 +181,9 @@ Options
|
||||
</br>
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% if examples or plainexamples -%}
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
@@ -178,10 +198,12 @@ Examples
|
||||
|
||||
|
||||
{% if returndocs -%}
|
||||
|
||||
|
||||
Return Values
|
||||
-------------
|
||||
|
||||
Common return values are documented here :doc:`common_return_values`, the following are the fields unique to this module:
|
||||
Common return values are documented :ref:`here <common_return_values>`, the following are the fields unique to this module:
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -255,7 +277,10 @@ Common return values are documented here :doc:`common_return_values`, the follow
|
||||
</br>
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% if notes -%}
|
||||
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
@@ -263,24 +288,40 @@ Notes
|
||||
{% for note in notes %}
|
||||
- @{ note | convert_symbols_to_format }@
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% endif %}
|
||||
{% if author is defined -%}
|
||||
|
||||
|
||||
Author
|
||||
~~~~~~
|
||||
|
||||
{% for author_name in author %}
|
||||
* @{ author_name }@
|
||||
{% endfor %}
|
||||
|
||||
|
||||
{% endif %}
|
||||
{% if not deprecated %}
|
||||
{% set support = { 'core': 'The Ansible Core Team', 'network': 'The Ansible Network Team', 'certified': 'an Ansible Partner', 'community': 'The Ansible Community', 'curated': 'A Third Party'} %}
|
||||
{% set module_states = { 'preview': 'it is not guaranteed to have a backwards compatible interface', 'stableinterface': 'the maintainers for this module guarantee that no backward incompatible interface changes will be made'} %}
|
||||
|
||||
{% if metadata %}
|
||||
{% if metadata.status %}
|
||||
|
||||
|
||||
Status
|
||||
~~~~~~
|
||||
|
||||
{% for cur_state in metadata.status %}
|
||||
This module is flagged as **@{cur_state}@** which means that @{module_states[cur_state]}@.
|
||||
{% endfor %}
|
||||
|
||||
|
||||
{% endif %}
|
||||
{% if metadata.supported_by in ('core', 'network') %}
|
||||
|
||||
|
||||
Maintenance Info
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -291,5 +332,5 @@ refer to this `knowledge base article<https://access.redhat.com/articles/rhel-to
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
|
||||
For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`dev_guide/testing` and :doc:`dev_guide/developing_modules`.
|
||||
For help in developing on modules, should you be so inclined, please read :doc:`../../community`, :doc:`../../dev_guide/testing` and :doc:`../../dev_guide/developing_modules`.
|
||||
|
||||
|
||||
9
docs/templates/plugins_by_category.rst.j2
vendored
Normal file
9
docs/templates/plugins_by_category.rst.j2
vendored
Normal file
@@ -0,0 +1,9 @@
|
||||
Plugin Index
|
||||
============
|
||||
|
||||
|
||||
.. toctree:: :maxdepth: 1
|
||||
|
||||
{% for name in categories %}
|
||||
list_of_@{ name }@_plugins
|
||||
{% endfor %}
|
||||
15
docs/templates/plugins_by_support.rst.j2
vendored
Normal file
15
docs/templates/plugins_by_support.rst.j2
vendored
Normal file
@@ -0,0 +1,15 @@
|
||||
.. _@{ slug }@:
|
||||
|
||||
Plugins Maintained by the @{ maintainers }@
|
||||
``````````````````````````@{ '`' * maintainers | length }@
|
||||
|
||||
.. toctree:: :maxdepth: 1
|
||||
|
||||
{% for module in modules | sort %}
|
||||
@{ module }@{% if module_info[module]['deprecated'] %} **(D)**{% endif %} - @{ module_info[module]['doc']['short_description'] }@ <plugins/@{ module_info[module]['primary_category'] }@/@{ module }@>
|
||||
{% endfor %}
|
||||
|
||||
.. note::
|
||||
- **(D)**: This marks a plugin as deprecated, which means a plugin is kept for backwards compatibility but usage is discouraged.
|
||||
The plugin documentation details page may explain more about this rationale.
|
||||
|
||||
Reference in New Issue
Block a user