docs: add argument specs to roles

[gardar]

Enables parameter validation in roles and opens up the possibility to auto generate docs with antsibull-docs

[paulfantom]

Are those files something that could be generated from defaults.yaml or would we need to remember to change them when defaults.yaml are changed?

[gardar]

Unfortunately they are managed completely separate from the defaults. Here's a discussion on the topic, but sadly it didn't go anywhere. ansible/ansible#77664
We could go the same route as the OP in that issue and have a script that auto generates the defaults from the argument specs.

With that being said, you would discover pretty quickly when they are missing because the role is validated against the argument specs and you will get an error if you supply incorrect parameters to the role.

[gardar]

We can however stop updating the readme and perhaps remove most of it, because docs can be auto generated from the argument specs.

[paulfantom]

With that being said, you would discover pretty quickly when they are missing because the role is validated against the argument specs and you will get an error if you supply incorrect parameters to the role.

That makes sense. Especially when we have a validation check in CI.

[towolf]

@gardar can't use 0.1.4 due to this:

[gardar]

Thanks for the heads up @towolf I've pushed a fix here: #50