From 9b6fdad5a109563bc7b4f073311564e705b0f432 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Feb 2024 13:14:44 +0100 Subject: [PATCH] Improve role argspec documentation (#1126) * Extend description for 'author'. * Improve option keyword descriptions. (cherry picked from commit be66e621614c40de6759095a1a9bb8b37a14fcf1) --- .../docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 316d164c729..d33a52e9c78 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -303,7 +303,8 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :author: * Name of the entry point authors. - * Use a multi-line list if there is more than one author. + * This can be a single string or a list of strings. Use one list entry per author. + If there is only a single author, use a string or a one-element list. :options: @@ -317,6 +318,8 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :description: * Detailed explanation of what this option does. It should be written in full sentences. + * This can be a single string or a list of strings. In case this is a list of strings, every list + element is a new paragraph. :version_added: @@ -336,11 +339,11 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :default: - * If ``required`` is false/missing, ``default`` may be specified (assumed 'null' if missing). + * If ``required`` is ``false``/missing, ``default`` may be specified (assumed ``null`` if missing). * Ensure that the default value in the docs matches the default value in the code. The actual default for the role variable will always come from ``defaults/main.yml``. * The default field must not be listed as part of the description unless it requires additional information or conditions. - * If the option is a boolean value, you should use `true/false` if you want to be compatible with `ansible-lint`. + * If the option is a boolean value, you should use ``true``/``false`` if you want to be compatible with ``ansible-lint``. :choices: