ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

validate-modules --arg-spec (#21331)

Browse source 
* validate-modules --arg-spec

* Update developing_modules_documenting.rst

* Never mock out ansible or ansible.module_utils

* No more false positives
This commit is contained in:
John R Barker 2017-02-15 08:09:08 +00:00 committed by GitHub
parent 47141b8426
commit 53ac312382
2 changed files with 16 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
View file

@ -41,6 +41,7 @@ The following fields can be used and are all required unless specified otherwise
* As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives. * As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
* Unlike ``description:`` this field should not have a trailing full stop. * Unlike ``description:`` this field should not have a trailing full stop.
* ``description:`` * ``description:``
* A detailed description (generally two or more sentences). * A detailed description (generally two or more sentences).
* Must be written in full sentences, i.e. with capital letters and fullstops. * Must be written in full sentences, i.e. with capital letters and fullstops.
* Shouldn't mention the name module. * Shouldn't mention the name module.
@ -62,10 +63,10 @@ The following fields can be used and are all required unless specified otherwise
* ``required:`` * ``required:``
Only needed if true, otherwise it is assumed to be false. Only needed if true, otherwise it is assumed to be false.
* ``default:`` * ``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 parameter in the docs matches the default parameter in the code. * Ensure that the default parameter in the docs matches the default parameter in the code.
* The default option must not be listed as part of the description. * The default option must not be listed as part of the description.
* ``choices:`` * ``choices:``
List of option values. Should be absent if empty. List of option values. Should be absent if empty.
* ``aliases:`` * ``aliases:``
@ -173,6 +174,14 @@ Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` direc
run the command: ``make webdocs``. The new 'modules.html' file will be run the command: ``make webdocs``. The new 'modules.html' file will be
built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory. built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory.
To test your documentation against your ``argument_spec`` you can use ``validate-modules``. Note that this option isn't currently enabled in Shippable due to the time it takes to run.
.. code-block:: shell-session
# If you don't already, ensure you are using your local checkout
$ source hacking/env-setup
$ ./test/sanity/validate-modules/validate-modules --arg-spec --warnings lib/ansible/modules/your/modules/
.. tip:: .. tip::
If you're having a problem with the syntax of your YAML you can If you're having a problem with the syntax of your YAML you can

4
test/sanity/validate-modules/module_args.py
View file

@ -71,6 +71,10 @@ def add_mocks(filename):
parts = module.split('.') parts = module.split('.')
for i in range(len(parts)): for i in range(len(parts)):
dotted = '.'.join(parts[:i+1]) dotted = '.'.join(parts[:i+1])
# Never mock out ansible or ansible.module_utils
# we may get here if a specific module_utils file needed mocked
if dotted in ('ansible', 'ansible.module_utils',):
continue
sys.modules[dotted] = sys_mock sys.modules[dotted] = sys_mock
sys_mocks.append(dotted) sys_mocks.append(dotted)