Use multiple collection filters for new enough ansible-doc versions

changelogs/fragments/213-ansible-doc-filters.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Support multiple filters in ``ansible-doc`` of ansible-core 2.16 and later. This makes building docsites and linting more efficient when documentation for more than one and less than all installed collections needs to be queried (https://github.com/ansible-community/antsibull-docs/issues/193, https://github.com/ansible-community/antsibull-docs/pull/213)."

src/antsibull_docs/docs_parsing/ansible_doc.py

@@ -122,10 +122,10 @@ async def get_collection_metadata(
     return collection_metadata
 
 
-async def get_ansible_core_version(
+async def _import_ansible_core_version(
     venv: VenvRunner | FakeVenvRunner,
     env: dict[str, str] | None = None,
-) -> PypiVer:
+) -> PypiVer | None:
     p = await venv.async_log_run(
         ["python", "-c", "import ansible.release; print(ansible.release.__version__)"],
         env=env,
@@ -134,6 +134,16 @@ async def get_ansible_core_version(
     output = p.stdout.strip()
     if p.returncode == 0 and output:
         return PypiVer(output)
+    return None
+
+
+async def get_ansible_core_version(
+    venv: VenvRunner | FakeVenvRunner,
+    env: dict[str, str] | None = None,
+) -> PypiVer:
+    version = await _import_ansible_core_version(venv, env)
+    if version is not None:
+        return version
 
     try:
         # Fallback: use `ansible --version`

src/antsibull_docs/docs_parsing/ansible_doc_core_213.py

@@ -14,6 +14,7 @@
 import semantic_version as semver
 from antsibull_core.logging import log
 from antsibull_core.vendored.json_utils import _filter_non_json_lines
+from packaging.version import Version as PypiVer
 
 from ..constants import DOCUMENTABLE_PLUGINS
 from . import AnsibleCollectionMetadata, _get_environment
@@ -69,8 +70,21 @@ def should_flatmap(
     return meta.docs_config.flatmap
 
 
+def _get_ansible_doc_filters(
+    ansible_core_version: PypiVer, collection_names: list[str] | None
+) -> list[str]:
+    if collection_names and len(collection_names) == 1:
+        return collection_names[:1]
+    if collection_names and ansible_core_version >= PypiVer("2.16.0.dev0"):
+        # ansible-doc of ansible-core 2.16.0.dev0 or later allows multiple filters
+        return collection_names
+    # ansible-doc of ansible-core < 2.16 only allows *one* filter
+    return []
+
+
 async def get_ansible_plugin_info(
     venv: VenvRunner | FakeVenvRunner,
+    ansible_core_version: PypiVer,
     collection_dir: str | None,
     collection_names: list[str] | None = None,
     fetch_all_installed: bool = False,
@@ -82,6 +96,8 @@ async def get_ansible_plugin_info(
     Retrieve information about all of the Ansible Plugins. Requires ansible-core 2.13+.
 
     :arg venv: A VenvRunner into which Ansible has been installed.
+    :arg ansible_core_version: The version of ansible-core. Needed to figure out how
+                               many filters can be provided to ansible-doc.
     :arg collection_dir: Directory in which the collections have been installed.
                          If ``None``, the collections are assumed to be in the current
                          search path for Ansible.
@@ -106,11 +122,9 @@ async def get_ansible_plugin_info(
     )
 
     flog.debug("Retrieving and loading plugin documentation")
-    if collection_names and len(collection_names) == 1:
-        # ansible-doc only allows *one* filter
-        ansible_doc_output = await _call_ansible_doc(venv, env, collection_names[0])
-    else:
-        ansible_doc_output = await _call_ansible_doc(venv, env)
+    ansible_doc_output = await _call_ansible_doc(
+        venv, env, *_get_ansible_doc_filters(ansible_core_version, collection_names)
+    )
 
     flog.debug("Retrieving collection metadata")
     collection_metadata = await get_collection_metadata(venv, env, collection_names)

src/antsibull_docs/docs_parsing/parsing.py

@@ -63,19 +63,23 @@ async def get_ansible_plugin_info(
     app_ctx = app_context.app_ctx.get()
 
     doc_parsing_backend = app_ctx.doc_parsing_backend
+    ansible_core_version = None
     if doc_parsing_backend == "auto":
-        version = await get_ansible_core_version(venv)
-        flog.debug(f"Ansible-core version: {version}")
-        if version < PypiVer("2.13.0.dev0"):
+        ansible_core_version = await get_ansible_core_version(venv)
+        flog.debug(f"Ansible-core version: {ansible_core_version}")
+        if ansible_core_version < PypiVer("2.13.0.dev0"):
             raise RuntimeError(
-                f"Unsupported ansible-core version {version}. Need 2.13.0 or later."
+                f"Unsupported ansible-core version {ansible_core_version}. Need 2.13.0 or later."
             )
         doc_parsing_backend = "ansible-core-2.13"
         flog.debug(f"Auto-detected docs parsing backend: {doc_parsing_backend}")
     if doc_parsing_backend == "ansible-core-2.13":
+        if ansible_core_version is None:
+            ansible_core_version = await get_ansible_core_version(venv)
         return await ansible_doc_core_213_get_ansible_plugin_info(
             venv,
-            collection_dir,
+            ansible_core_version=ansible_core_version,
+            collection_dir=collection_dir,
             collection_names=collection_names,
             fetch_all_installed=fetch_all_installed,
         )

tests/functional/ansible-doc-cache-all-others.json

@@ -3787,7 +3787,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a unique list of all the elements of the first list that do not appear in the second one."
+      "Provide a unique list of all the elements of the first list that do not appear in the second one.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/difference.yml",
      "name": "difference",
@@ -3946,7 +3947,7 @@
        "required": true,
        "type": "raw"
       },
-      "contianer": {
+      "container": {
        "description": "Dictionary or list from which to extract a value.",
        "required": true,
        "type": "raw"
@@ -4276,7 +4277,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a list with the common elements from other lists."
+      "Provide a list with the common elements from other lists.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/intersect.yml",
      "name": "intersect",
@@ -5339,7 +5341,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a unique list of all the elements unique to each list."
+      "Provide a unique list of all the elements unique to each list.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/symmetric_difference.yml",
      "name": "symmetric_difference",
@@ -5780,7 +5783,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a unique list of all the elements of two lists."
+      "Provide a unique list of all the elements of two lists.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/union.yml",
      "name": "union",
@@ -16983,7 +16987,7 @@
      "requirements": [
       "pip",
       "virtualenv",
-      "setuptools"
+      "setuptools or packaging"
      ],
      "short_description": "Manages Python library dependencies",
      "version_added": "0.7",
@@ -21043,10 +21047,9 @@
       "profile": {
        "description": [
         "Sets the profile of the user.",
-        "Does nothing when used with other platforms.",
         "Can set multiple profiles using comma separation.",
         "To delete all the profiles, use O(profile='').",
-        "Currently supported on Illumos/Solaris."
+        "Currently supported on Illumos/Solaris. Does nothing when used with other platforms."
        ],
        "type": "str",
        "version_added": "2.8",
@@ -21063,10 +21066,9 @@
       "role": {
        "description": [
         "Sets the role of the user.",
-        "Does nothing when used with other platforms.",
         "Can set multiple roles using comma separation.",
         "To delete all roles, use O(role='').",
-        "Currently supported on Illumos/Solaris."
+        "Currently supported on Illumos/Solaris. Does nothing when used with other platforms."
        ],
        "type": "str",
        "version_added": "2.8",
@@ -21173,8 +21175,7 @@
       "umask": {
        "description": [
         "Sets the umask of the user.",
-        "Does nothing when used with other platforms.",
-        "Currently supported on Linux.",
+        "Currently supported on Linux. Does nothing when used with other platforms.",
         "Requires O(local) is omitted or V(False)."
        ],
        "type": "str",
@@ -22977,7 +22978,8 @@
         "O(ns2.col.bar#filter:foo[])",
         "O(ext.col.foo#module:foo[baz].bar)",
         "RV(ext.col.foo#module:baz)",
-        "RV(ext.col.foo#module:baz[ ])"
+        "RV(ext.col.foo#module:baz[ ])",
+        "RV(ansible.builtin.stat#module:stat[foo.bar])"
        ]
       },
       "existing": {

tests/functional/ansible-doc-cache-all.json

@@ -3787,7 +3787,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a unique list of all the elements of the first list that do not appear in the second one."
+      "Provide a unique list of all the elements of the first list that do not appear in the second one.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/difference.yml",
      "name": "difference",
@@ -3946,7 +3947,7 @@
        "required": true,
        "type": "raw"
       },
-      "contianer": {
+      "container": {
        "description": "Dictionary or list from which to extract a value.",
        "required": true,
        "type": "raw"
@@ -4276,7 +4277,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a list with the common elements from other lists."
+      "Provide a list with the common elements from other lists.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/intersect.yml",
      "name": "intersect",
@@ -5339,7 +5341,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a unique list of all the elements unique to each list."
+      "Provide a unique list of all the elements unique to each list.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/symmetric_difference.yml",
      "name": "symmetric_difference",
@@ -5780,7 +5783,8 @@
      "author": "Brian Coca (@bcoca)",
      "collection": "ansible.builtin",
      "description": [
-      "Provide a unique list of all the elements of two lists."
+      "Provide a unique list of all the elements of two lists.",
+      "Items in the resulting list are returned in arbitrary order."
      ],
      "filename": "/ansible/plugins/filter/union.yml",
      "name": "union",
@@ -16949,7 +16953,7 @@
      "requirements": [
       "pip",
       "virtualenv",
-      "setuptools"
+      "setuptools or packaging"
      ],
      "short_description": "Manages Python library dependencies",
      "version_added": "0.7",
@@ -21009,10 +21013,9 @@
       "profile": {
        "description": [
         "Sets the profile of the user.",
-        "Does nothing when used with other platforms.",
         "Can set multiple profiles using comma separation.",
         "To delete all the profiles, use O(profile='').",
-        "Currently supported on Illumos/Solaris."
+        "Currently supported on Illumos/Solaris. Does nothing when used with other platforms."
        ],
        "type": "str",
        "version_added": "2.8",
@@ -21029,10 +21032,9 @@
       "role": {
        "description": [
         "Sets the role of the user.",
-        "Does nothing when used with other platforms.",
         "Can set multiple roles using comma separation.",
         "To delete all roles, use O(role='').",
-        "Currently supported on Illumos/Solaris."
+        "Currently supported on Illumos/Solaris. Does nothing when used with other platforms."
        ],
        "type": "str",
        "version_added": "2.8",
@@ -21139,8 +21141,7 @@
       "umask": {
        "description": [
         "Sets the umask of the user.",
-        "Does nothing when used with other platforms.",
-        "Currently supported on Linux.",
+        "Currently supported on Linux. Does nothing when used with other platforms.",
         "Requires O(local) is omitted or V(False)."
        ],
        "type": "str",
@@ -22896,7 +22897,8 @@
         "O(ns2.col.bar#filter:foo[])",
         "O(ext.col.foo#module:foo[baz].bar)",
         "RV(ext.col.foo#module:baz)",
-        "RV(ext.col.foo#module:baz[ ])"
+        "RV(ext.col.foo#module:baz[ ])",
+        "RV(ansible.builtin.stat#module:stat[foo.bar])"
        ]
       },
       "existing": {