Also lint seealso references. (#171)

ansible-community · Jun 24, 2023 · e3122b3 · e3122b3
1 parent c2a176d
commit e3122b3
Show file tree

Hide file tree

Showing 30 changed files with 772 additions and 50 deletions.
diff --git a/changelogs/fragments/171-lint.yml b/changelogs/fragments/171-lint.yml
@@ -0,0 +1,2 @@
+minor_changes:
+  - "Collection docs linter - also validate ``seealso`` module and plugin destinations (https://github.com/ansible-community/antsibull-docs/issues/168, https://github.com/ansible-community/antsibull-docs/pull/171)."
diff --git a/src/antsibull_docs/lint_plugin_docs.py b/src/antsibull_docs/lint_plugin_docs.py
@@ -272,15 +272,17 @@ class _MarkupValidator:
     _disallow_semantic_markup: bool
 
     def _report_disallowed_collection(
-        self, part: dom.AnyPart, plugin_fqcn: str, key: str
+        self, part: dom.AnyPart | None, plugin_fqcn: str, key: str
     ) -> None:
+        if part:
+            key = f"{key}: {part.source}"
         self.errors.append(
-            f"{key}: {part.source}: a reference to the collection"
+            f"{key}: a reference to the collection"
             f" {_get_fqcn_collection_name(plugin_fqcn)} is not allowed"
         )
 
     def _validate_plugin_fqcn(
-        self, part: dom.AnyPart, plugin_fqcn: str, plugin_type: str, key: str
+        self, part: dom.AnyPart | None, plugin_fqcn: str, plugin_type: str, key: str
     ) -> bool:
         if self._validate_collections_refs == "self":
             if not plugin_fqcn.startswith(self._collection_name_prefix):
@@ -291,8 +293,9 @@ def _validate_plugin_fqcn(
             return True
         if self._name_collector.is_valid_collection(plugin_fqcn):
             prefix = "" if plugin_type in ("role", "module") else " plugin"
+            key_prefix = f"{key}: {part.source}" if part else key
             self.errors.append(
-                f"{key}: {part.source}: there is no {plugin_type}{prefix} {plugin_fqcn}"
+                f"{key_prefix}: there is no {plugin_type}{prefix} {plugin_fqcn}"
             )
         elif self._disallow_unknown_collection_refs:
             self._report_disallowed_collection(part, plugin_fqcn, key)
@@ -377,6 +380,18 @@ def _validate_markup_entry(
                 if par_elem.type == dom.PartType.PLUGIN:
                     self._validate_plugin(t.cast(dom.PluginPart, par_elem), key)
 
+    def _check_seealso(self, seealso: list[t.Any], key: str):
+        for index, entry in enumerate(seealso):
+            if not isinstance(entry, Mapping):
+                continue
+            entry_key = f"{key}[{index + 1}]"
+            if "module" in entry:
+                self._validate_plugin_fqcn(None, entry["module"], "module", entry_key)
+            if "plugin" in entry and "plugin_type" in entry:
+                self._validate_plugin_fqcn(
+                    None, entry["plugin"], entry["plugin_type"], key
+                )
+
     def __init__(
         self,
         name_collector: _NameCollector,
@@ -400,6 +415,18 @@ def callback(entry: str, key: str, role_entrypoint: str | None = None) -> None:
 
         walk_plugin_docs_texts(plugin_record, callback)
 
+        if isinstance(plugin_record.get("doc"), Mapping):
+            if isinstance(plugin_record["doc"].get("seealso"), Sequence):
+                self._check_seealso(
+                    plugin_record["doc"]["seealso"], key="DOCUMENTATION -> seealso"
+                )
+        if isinstance(plugin_record.get("entry_points"), Mapping):
+            for entry_point, data in sorted(plugin_record["entry_points"].items()):
+                if isinstance(data.get("seealso"), Sequence):
+                    self._check_seealso(
+                        data["seealso"], key=f"entry_points -> {entry_point} -> seealso"
+                    )
+
 
 def _validate_markup(
     name_collector: _NameCollector,

diff --git a/tests/functional/ansible-doc-cache-all-others.json b/tests/functional/ansible-doc-cache-all-others.json
@@ -22634,6 +22634,9 @@
       }
      },
      "requirements": "Foo.",
+     "seealso": {
+      "foo": "bar"
+     },
      "version_added": "foo",
      "version_added_collection": "ns.col2"
     },
@@ -22716,6 +22719,40 @@
       }
      },
      "requirements": "Foo.",
+     "seealso": [
+      {
+       "module": "ns.col2.foo3"
+      },
+      {
+       "module": "ns.col2.foobarbaz"
+      },
+      {
+       "plugin": "ns.col2.foo4",
+       "plugin_type": "module"
+      },
+      {
+       "plugin": "ns.col2.foobarbaz",
+       "plugin_type": "inventory"
+      },
+      {
+       "description": "The service module.",
+       "module": "ansible.builtin.service"
+      },
+      {
+       "description": "A non-existing module.",
+       "module": "ansible.builtin.foobarbaz"
+      },
+      {
+       "description": "The linear strategy plugin.",
+       "plugin": "ansible.builtin.linear",
+       "plugin_type": "strategy"
+      },
+      {
+       "description": "A non-existing stragey plugin",
+       "plugin": "ansible.builtin.foobarbaz",
+       "plugin_type": "strategy"
+      }
+     ],
      "short_description": "Foo two"
     },
     "examples": "\nname: This is YAML.\n",
@@ -22956,12 +22993,18 @@
       {
        "module": "ns2.col.foo2"
       },
-      {
-       "module": "ns2.col.foo3"
-      },
       {
        "plugin": "ns2.col.foo",
        "plugin_type": "lookup"
+      },
+      {
+       "description": "The service module.",
+       "module": "ansible.builtin.service"
+      },
+      {
+       "description": "The ssh connection plugin.",
+       "plugin": "ansible.builtin.ssh",
+       "plugin_type": "connection"
       }
      ],
      "short_description": "Do some foo O(bar)",
@@ -23226,6 +23269,35 @@
   },
   "netconf": {},
   "role": {
+   "ns.col2.bar": {
+    "collection": "ns.col2",
+    "entry_points": {
+     "baz": {
+      "description": [
+       "This is the baz entrypoint of the bar role."
+      ],
+      "short_description": "Bar role, baz entrypoint"
+     },
+     "main": {
+      "author": [
+       "Felix Fontein (@felixfontein)"
+      ],
+      "description": [
+       "This is the bar role."
+      ],
+      "seealso": [
+       {
+        "module": "ns2.col.foo"
+       },
+       {
+        "module": "ns2.col.foobarbaz"
+       }
+      ],
+      "short_description": "Bar role"
+     }
+    },
+    "path": "ansible_collections/ns/col2"
+   },
    "ns2.col.foo": {
     "collection": "ns2.col",
     "entry_points": {

diff --git a/tests/functional/ansible-doc-cache-all.json b/tests/functional/ansible-doc-cache-all.json
@@ -22553,6 +22553,9 @@
       }
      },
      "requirements": "Foo.",
+     "seealso": {
+      "foo": "bar"
+     },
      "version_added": "foo",
      "version_added_collection": "ns.col2"
     },
@@ -22635,6 +22638,40 @@
       }
      },
      "requirements": "Foo.",
+     "seealso": [
+      {
+       "module": "ns.col2.foo3"
+      },
+      {
+       "module": "ns.col2.foobarbaz"
+      },
+      {
+       "plugin": "ns.col2.foo4",
+       "plugin_type": "module"
+      },
+      {
+       "plugin": "ns.col2.foobarbaz",
+       "plugin_type": "inventory"
+      },
+      {
+       "description": "The service module.",
+       "module": "ansible.builtin.service"
+      },
+      {
+       "description": "A non-existing module.",
+       "module": "ansible.builtin.foobarbaz"
+      },
+      {
+       "description": "The linear strategy plugin.",
+       "plugin": "ansible.builtin.linear",
+       "plugin_type": "strategy"
+      },
+      {
+       "description": "A non-existing stragey plugin",
+       "plugin": "ansible.builtin.foobarbaz",
+       "plugin_type": "strategy"
+      }
+     ],
      "short_description": "Foo two"
     },
     "examples": "\nname: This is YAML.\n",
@@ -22875,12 +22912,18 @@
       {
        "module": "ns2.col.foo2"
       },
-      {
-       "module": "ns2.col.foo3"
-      },
       {
        "plugin": "ns2.col.foo",
        "plugin_type": "lookup"
+      },
+      {
+       "description": "The service module.",
+       "module": "ansible.builtin.service"
+      },
+      {
+       "description": "The ssh connection plugin.",
+       "plugin": "ansible.builtin.ssh",
+       "plugin_type": "connection"
       }
      ],
      "short_description": "Do some foo O(bar)",
@@ -23145,6 +23188,35 @@
   },
   "netconf": {},
   "role": {
+   "ns.col2.bar": {
+    "collection": "ns.col2",
+    "entry_points": {
+     "baz": {
+      "description": [
+       "This is the baz entrypoint of the bar role."
+      ],
+      "short_description": "Bar role, baz entrypoint"
+     },
+     "main": {
+      "author": [
+       "Felix Fontein (@felixfontein)"
+      ],
+      "description": [
+       "This is the bar role."
+      ],
+      "seealso": [
+       {
+        "module": "ns2.col.foo"
+       },
+       {
+        "module": "ns2.col.foobarbaz"
+       }
+      ],
+      "short_description": "Bar role"
+     }
+    },
+    "path": "ansible_collections/ns/col2"
+   },
    "ns2.col.foo": {
     "collection": "ns2.col",
     "entry_points": {

diff --git a/tests/functional/ansible-doc-cache-ns.col2.json b/tests/functional/ansible-doc-cache-ns.col2.json
@@ -714,6 +714,9 @@
       }
      },
      "requirements": "Foo.",
+     "seealso": {
+      "foo": "bar"
+     },
      "version_added": "foo",
      "version_added_collection": "ns.col2"
     },
@@ -796,6 +799,40 @@
       }
      },
      "requirements": "Foo.",
+     "seealso": [
+      {
+       "module": "ns.col2.foo3"
+      },
+      {
+       "module": "ns.col2.foobarbaz"
+      },
+      {
+       "plugin": "ns.col2.foo4",
+       "plugin_type": "module"
+      },
+      {
+       "plugin": "ns.col2.foobarbaz",
+       "plugin_type": "inventory"
+      },
+      {
+       "description": "The service module.",
+       "module": "ansible.builtin.service"
+      },
+      {
+       "description": "A non-existing module.",
+       "module": "ansible.builtin.foobarbaz"
+      },
+      {
+       "description": "The linear strategy plugin.",
+       "plugin": "ansible.builtin.linear",
+       "plugin_type": "strategy"
+      },
+      {
+       "description": "A non-existing stragey plugin",
+       "plugin": "ansible.builtin.foobarbaz",
+       "plugin_type": "strategy"
+      }
+     ],
      "short_description": "Foo two"
     },
     "examples": "\nname: This is YAML.\n",
@@ -958,7 +995,37 @@
    }
   },
   "netconf": {},
-  "role": {},
+  "role": {
+   "ns.col2.bar": {
+    "collection": "ns.col2",
+    "entry_points": {
+     "baz": {
+      "description": [
+       "This is the baz entrypoint of the bar role."
+      ],
+      "short_description": "Bar role, baz entrypoint"
+     },
+     "main": {
+      "author": [
+       "Felix Fontein (@felixfontein)"
+      ],
+      "description": [
+       "This is the bar role."
+      ],
+      "seealso": [
+       {
+        "module": "ns2.col.foo"
+       },
+       {
+        "module": "ns2.col.foobarbaz"
+       }
+      ],
+      "short_description": "Bar role"
+     }
+    },
+    "path": "ansible_collections/ns/col2"
+   }
+  },
   "shell": {},
   "strategy": {},
   "test": {},
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		minor_changes:
		- "Collection docs linter - also validate ``seealso`` module and plugin destinations (https://github.com/ansible-community/antsibull-docs/issues/168, https://github.com/ansible-community/antsibull-docs/pull/171)."