Skip to content

Commit

Permalink
Use multiple collection filters for new enough ansible-doc versions (#…
Browse files Browse the repository at this point in the history
…213)

* ansible-doc can filter by more than one collection.

* Add missing .license files.

* Remove no longer needed fixtures.
  • Loading branch information
felixfontein authored Sep 15, 2023
1 parent 1288d70 commit e358387
Show file tree
Hide file tree
Showing 28 changed files with 79,378 additions and 1,490 deletions.
2 changes: 2 additions & 0 deletions changelogs/fragments/213-ansible-doc-filters.yml
Original file line number Diff line number Diff line change
@@ -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)."
14 changes: 12 additions & 2 deletions src/antsibull_docs/docs_parsing/ansible_doc.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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`
Expand Down
24 changes: 19 additions & 5 deletions src/antsibull_docs/docs_parsing/ansible_doc_core_213.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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.
Expand All @@ -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)
Expand Down
14 changes: 9 additions & 5 deletions src/antsibull_docs/docs_parsing/parsing.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
Expand Down
28 changes: 15 additions & 13 deletions tests/functional/ansible-doc-cache-all-others.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -3946,7 +3947,7 @@
"required": true,
"type": "raw"
},
"contianer": {
"container": {
"description": "Dictionary or list from which to extract a value.",
"required": true,
"type": "raw"
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -16983,7 +16987,7 @@
"requirements": [
"pip",
"virtualenv",
"setuptools"
"setuptools or packaging"
],
"short_description": "Manages Python library dependencies",
"version_added": "0.7",
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": {
Expand Down
28 changes: 15 additions & 13 deletions tests/functional/ansible-doc-cache-all.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -3946,7 +3947,7 @@
"required": true,
"type": "raw"
},
"contianer": {
"container": {
"description": "Dictionary or list from which to extract a value.",
"required": true,
"type": "raw"
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -16949,7 +16953,7 @@
"requirements": [
"pip",
"virtualenv",
"setuptools"
"setuptools or packaging"
],
"short_description": "Manages Python library dependencies",
"version_added": "0.7",
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": {
Expand Down
Loading

0 comments on commit e358387

Please sign in to comment.