Move modules to beginning of plugin index (#336)

* Remove superfluous part.

* Move 'Modules' to beginning of plugin list.

* Add tests.

* Forgot newline.

antsibull/data/docsite/plugins_by_collection.rst.j2

@@ -2,6 +2,12 @@
 :orphan:
 {% endif %}
 
+{% macro list_plugins(plugin_type) %}
+{%   for name, desc in plugin_maps[plugin_type].items() | sort %}
+* :ref:`@{ name }@ <ansible_collections.@{ collection_name }@.@{ name }@_@{ plugin_type }@>` -- @{ desc | rst_ify | indent(width=2) }@
+{%   endfor %}
+{% endmacro %}
+
 .. _plugins_in_@{collection_name}@:
 
 @{collection_name.title()}@
@@ -33,42 +39,33 @@ Plugin Index
 ------------
 
 {% if plugin_maps | reject('eq', 'role') | list %}
-These are the plugins in the @{collection_name}@ collection
+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 | rejectattr('0', 'eq', 'role') %}
+{% for category in plugin_maps | reject('eq', 'role') | sort | move_first('module') %}
 
 {%   if category == 'module' %}
 Modules
 ~~~~~~~
-{%   elif category == 'role' %}
-Roles
-~~~~~
 {%   else %}
 @{ category | capitalize }@ Plugins
 @{ '~' * ((category | length) + 8) }@
 {%   endif %}
 
-{%   for name, desc in plugins.items() | sort %}
-* :ref:`@{ name }@ <ansible_collections.@{ collection_name }@.@{ name }@_@{ category }@>` -- @{ desc | rst_ify | indent(width=2) }@
-{%   endfor %}
+@{   list_plugins(category) }@
 {% 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 %}
+These are the roles in the @{collection_name}@ collection:
 
+@{   list_plugins('role') }@
 {% endif %}
 
-
 .. seealso::
 
     List of :ref:`collections <list_of_collections>` with docs hosted here.

antsibull/jinja2/environment.py

@@ -7,7 +7,9 @@
 
 from jinja2 import Environment, FileSystemLoader, PackageLoader
 
-from .filters import do_max, documented_type, html_ify, rst_ify, rst_fmt, rst_xline
+from .filters import (
+    do_max, documented_type, html_ify, rst_ify, rst_fmt, rst_xline, move_first,
+)
 from .tests import still_relevant, test_list
 
 
@@ -64,6 +66,7 @@ def doc_environment(template_location):
     env.filters['fmt'] = rst_fmt
     env.filters['xline'] = rst_xline
     env.filters['documented_type'] = documented_type
+    env.filters['move_first'] = move_first
     env.tests['list'] = test_list
     env.tests['still_relevant'] = still_relevant
 

antsibull/jinja2/filters.py

@@ -103,3 +103,20 @@ def rst_xline(width, char="="):
     ''' return a restructured text line of a given length '''
 
     return char * width
+
+
+def move_first(sequence, *move_to_beginning):
+    ''' return a copy of sequence where the elements which are in move_to_beginning are
+        moved to its beginning if they appear in the list '''
+
+    remaining = list(sequence)
+    beginning = []
+    for elt in move_to_beginning:
+        try:
+            remaining.remove(elt)
+            beginning.append(elt)
+        except ValueError:
+            # elt not found in remaining
+            pass
+
+    return beginning + remaining

tests/units/test_jinja2.py

@@ -1,6 +1,6 @@
 import pytest
 
-from antsibull.jinja2.filters import rst_ify
+from antsibull.jinja2.filters import rst_ify, move_first
 
 
 RST_IFY_DATA = {
@@ -31,3 +31,18 @@
 @pytest.mark.parametrize('text, expected', RST_IFY_DATA.items())
 def test_rst_ify(text, expected):
     assert rst_ify(text) == expected
+
+
+MOVE_FIRST_DATA = [
+    ([], [], []),
+    (['a', 'b', 'c'], ['d'], ['a', 'b', 'c']),
+    (['a', 'b', 'c'], ['b'], ['b', 'a', 'c']),
+    (['a', 'b', 'b', 'c'], ['b'], ['b', 'a', 'b', 'c']),
+    (['a', 'b', 'c'], ['b', 'c'], ['b', 'c', 'a']),
+    (['a', 'b', 'c'], ['c', 'b'], ['c', 'b', 'a']),
+]
+
+
+@pytest.mark.parametrize('input, move_to_beginning, expected', MOVE_FIRST_DATA)
+def test_move_first(input, move_to_beginning, expected):
+    assert move_first(input, *move_to_beginning) == expected