There are common parameters in all modules like ipaadmin_principal and
ipaadmin_password. As this list of common parameters will be extended
soon, there is a need to reduce the code and documentation duplicates.
A ModuleDocFragment is added to provide the module documentation for the
common parameters. This is used in the modules with
extends_documentation_fragment.
ansible_freeipa_module has additional ipamodule_base_spec and
get_ipamodule_base_vars. ipamodule_base_spec extends argument_spec in
the module and get_ipamodule_base_vars is used to return a dict
containing the common parameters.
ANSIBLE_LIBRARY needs to be set properly for new Ansible version 4.0.0
to make sure that it is able to find the module that is checked.
For every file that needs to be checked, there is a separate ansible-doc
call. ANSIBLE_LIBRARY is set using os.path.dirname on the module_path.
Currently the script is failing with The given path '...' is not valid
if a path is not handled by the script. This is resulting in issues if
module_utils and action plugins are updated for example.
The solution is to simply ignore paths that are not handled.
This script can check modules in roles and also plugins folder to have
a valid documentation section. It is using anisble-doc internally.
usage: Usage: ansible-doc-test [options] [path]
optional arguments:
-h, --help show this help message and exit
-v increase output verbosity
There are different verbose levels:
-v Shows the modules that are tested at the moment.
-vv Shows the modules and also the doc output.
You can use the script to check specific modules, roles or modules in roles.
Here are some examples:
Test specific module with verbose level 1:
$ utils/ansible-doc-test -vv plugins/modules/ipauser.py
Test all modules in plugins folder:
$ utils/ansible-doc-test -v plugins
Test ipaserver_prepare.py in ipaserver role:
$ utils/ansible-doc-test -v roles/ipaserver/library/ipaserver_prepare.py
Test all modules in ipaserver role:
$ utils/ansible-doc-test -v roles/ipaserver
Test all roles:
$ utils/ansible-doc-test -v roles
Test all roles and modules in plugins:
$ utils/ansible-doc-test -v
