Clarify documentation - argument_specs.yml "author" - list or string?

Get Help
1

Looking at this page in the documentation. The description of “entry-point-name → author” says to “Use a multi-line list if there is more than one author.”

What exactly is a “multi-line list”?

  • Should it be an actual list, containing mutliple strings?

    argument_specs :
  main :
    author :
      - "Name 1 <email>"
      - "Name 2 <email>"

  • Should be a multi-line string?

    argument_specs :
  main :
    author : |-
      Name 1 <email>
      Name 2 <email>
2

It should be a string if there is 1 author, and a list for multiple. I’m guessing the multi-line recommendation is to deter from a comma-separated name1, name1 or bracketed list [name1, name2] for readability.

3

I’ll take your word for it. I’m not familiar enough with the code to know where to find the code which parses this file.

This is yet another case where Ansible’s documentation is lacking.

Actually, there’s another question: is there a way to manually TEST the contents of this file? Other than just yamllint, of course.

5

@shertel

for below topic?

1 Like
6

Oops, yes. Thank you.

1 Like
7

I’m not aware of any validation for authors in role argument spec. The argspec options are validated against the available variables when running the role.

Here’s the action plugin that parses the file ansible.builtin.validate_argument_spec module – Validate role argument specs. — Ansible Documentation.

8

Assuming the role is part of a collection: antsibull-docs lint-collection-docs does validation on the argument spec.

Ansible-lint also validates it, it probably also work with stand-alone roles outside collections.

1 Like
9

I created a PR to improve the docs: Improve role argspec documentation by felixfontein · Pull Request #1126 · ansible/ansible-documentation · GitHub

(More infos on antsibull-docs lint-collection-docs: Creating a collection docsite - antsibull-docs – Ansible Documentation Build Scripts)

2 Likes