role argument spec: allow author, top-level description, and todo to be a string instead of a list of stings

changelogs/fragments/227-role-argspec-str-to-list.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "For role argument specs, allow ``author``, ``description``, and ``todo`` to be a string instead of a list of strings, similarly as with ansible-doc and with modules and plugins (https://github.com/ansible-community/antsibull-docs/pull/227)."

src/antsibull_docs/schemas/docs/role.py

@@ -26,6 +26,7 @@
     SeeAlsoLinkSchema,
     SeeAlsoModSchema,
     SeeAlsoRefSchema,
+    list_from_scalars,
 )
 
 _SENTINEL = object()
@@ -69,6 +70,16 @@ class RoleEntrypointSchema(BaseModel):
 
     options: dict[str, RoleOptionsSchema] = {}
 
+    @p.validator(
+        "author",
+        "description",
+        "todo",
+        pre=True,
+    )
+    # pylint:disable=no-self-argument
+    def list_from_scalars(cls, obj):
+        return list_from_scalars(obj)
+
 
 class RoleSchema(BaseModel):
     """Documentation for roles."""

tests/functional/schema/good_data/one_role.json

@@ -77,7 +77,17 @@
                     }
                 },
                 "short_description": "Do account key rollover",
+                "todo": [
+                    "something",
+                    "something else"
+                ],
                 "version_added": "0.1.0"
+            },
+            "other": {
+                "author": "Felix Fontein (@felixfontein)",
+                "description": "This is a one-paragraph description",
+                "short_description": "Do nothing",
+                "todo": "something"
             }
         },
         "path": "/path/to/ansible_collections/felixfontein/acme"

tests/functional/schema/good_data/one_role_results.json

@@ -79,7 +79,23 @@
                     }
                 },
                 "short_description": "Do account key rollover",
+                "todo": [
+                    "something",
+                    "something else"
+                ],
                 "version_added": "0.1.0"
+            },
+            "other": {
+                "author": [
+                    "Felix Fontein (@felixfontein)"
+                ],
+                "description": [
+                    "This is a one-paragraph description"
+                ],
+                "short_description": "Do nothing",
+                "todo": [
+                    "something"
+                ]
             }
         },
         "path": "/path/to/ansible_collections/felixfontein/acme"