mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Pull documentation of ansible.module_utils.basic from (improved) doc strings. (#48416)
This commit is contained in:
Andreas Krüger
Alicia Cozine
parent
ba4c2ebeac
commit
18bf48cec2
6 changed files with 47 additions and 66 deletions
|
|
@ -4,7 +4,9 @@
|
|||
Ansible API Documentation
|
||||
*************************
|
||||
|
||||
The Ansible API is under construction. These stub references will be documented in future.
|
||||
The Ansible API is under construction. These stub references will be documented in future. For now, there is a legacy :ref:`documentation page <ansible.module_utils>` for the ``AnsibleModule``.
|
||||
|
||||
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
|
@ -48,7 +50,8 @@ Deprecated in favor of ansibleModule._selinux_special_fs.
|
|||
Classes
|
||||
=======
|
||||
|
||||
.. py:class:: ansible.module_utils.basic.AnsibleModule
|
||||
.. py:class:: ``ansible.module_utils.basic.AnsibleModule``
|
||||
:noindex:
|
||||
|
||||
The basic utilities for AnsibleModule.
|
||||
|
||||
|
|
|
|||
|
|
@ -28,6 +28,12 @@ import os
|
|||
sys.path.insert(0, os.path.join('ansible', 'lib'))
|
||||
sys.path.append(os.path.abspath(os.path.join('..', '_extensions')))
|
||||
|
||||
# We want sphinx to document the ansible modules contained in this repository,
|
||||
# not those that may happen to be installed in the version
|
||||
# of Python used to run sphinx. When sphinx loads in order to document,
|
||||
# the repository version needs to be the one that is loaded:
|
||||
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib')))
|
||||
|
||||
VERSION = '2.7'
|
||||
AUTHOR = 'Ansible, Inc'
|
||||
|
||||
|
|
|
|||
2
docs/docsite/rst/reference_appendices/.rstcheck.cfg
Normal file
2
docs/docsite/rst/reference_appendices/.rstcheck.cfg
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
[rstcheck]
|
||||
ignore_directives=autoclass,automodule
|
||||
|
|
@ -5,65 +5,23 @@
|
|||
Ansible Reference: Module Utilities
|
||||
***************************************************************
|
||||
|
||||
This page documents the available utilities called with ``ansible.module_utils.util_name``.
|
||||
This page documents utilities intended to be helpful when writing
|
||||
Ansible modules in Python.
|
||||
|
||||
Generic
|
||||
--------
|
||||
.. glossary::
|
||||
|
||||
.. _ansible.module_utils.debug
|
||||
debug
|
||||
.. _ansible.module_utils.url
|
||||
url
|
||||
.. _ansible.module_utils.log
|
||||
log
|
||||
.. _ansible.module_utils.no_log
|
||||
no_log
|
||||
.. _Ansible.get_bin_path
|
||||
Ansible.get_bin_path
|
||||
|
||||
|
||||
.. _AnsibleModule:
|
||||
.. _ansible.module_utils.basic.AnsibleModule:
|
||||
|
||||
AnsibleModule
|
||||
--------------
|
||||
.. glossary::
|
||||
|
||||
ansible.module_utils.basic.AnsibleModule
|
||||
Utilities in module_utils.basic.AnsibleModule apply to all module types
|
||||
To use this functionality, include ``from ansible.module_utils.basic import AnsibleModule`` in your module.
|
||||
|
||||
.. _AnsibleModule.debug:
|
||||
AnsibleModule.debug
|
||||
.. _AnsibleModule._debug:
|
||||
AnsibleModule._debug
|
||||
.. _AnsibleModule._diff:
|
||||
AnsibleModule._diff
|
||||
.. _AnsibleModule.log:
|
||||
AnsibleModule.log
|
||||
.. _AnsibleModule.no_log:
|
||||
AnsibleModule.no_log
|
||||
.. _AnsibleModule.params:
|
||||
AnsibleModule.params
|
||||
.. _AnsibleModule.run_command:
|
||||
AnsibleModule.run_command
|
||||
.. _ansible.module_utils.basic.AnsibleModule._selinux_special_fs:
|
||||
ansible.module_utils.basic.AnsibleModule._selinux_special_fs
|
||||
(formerly ansible.module_utils.basic.SELINUX_SPECIAL_FS)
|
||||
.. autoclass:: ansible.module_utils.basic.AnsibleModule
|
||||
:members:
|
||||
|
||||
|
||||
.. _ansible.module_utils.basic:
|
||||
|
||||
Basic
|
||||
------
|
||||
.. glossary::
|
||||
|
||||
ansible.module_utils.basic
|
||||
Utilities in module_utils.basic apply to all module types.
|
||||
To use this functionality, include ``import ansible.module_utils.basic`` in your module.
|
||||
|
||||
.. _ansible.module_utils.basic.SELINUX_SPECIAL_FS:
|
||||
ansible.module_utils.basic.SELINUX_SPECIAL_FS
|
||||
*deprecated* replaced by :term:`ansible.module_utils.basic.AnsibleModule._selinux_special_fs`
|
||||
|
||||
.. _ansible.module_utils.basic._load_params:
|
||||
load_params
|
||||
.. automodule:: ansible.module_utils.basic
|
||||
:members:
|
||||
|
|
|
|||
|
|
@ -545,9 +545,8 @@ def bytes_to_human(size, isbits=False, unit=None):
|
|||
def human_to_bytes(number, default_unit=None, isbits=False):
|
||||
|
||||
'''
|
||||
Convert number in string format into bytes (ex: '2K' => 2048) or using unit argument
|
||||
ex:
|
||||
human_to_bytes('10M') <=> human_to_bytes(10, 'M')
|
||||
Convert number in string format into bytes (ex: '2K' => 2048) or using unit argument.
|
||||
example: human_to_bytes('10M') <=> human_to_bytes(10, 'M')
|
||||
'''
|
||||
m = re.search(r'^\s*(\d*\.?\d*)\s*([A-Za-z]+)?', str(number), flags=re.IGNORECASE)
|
||||
if m is None:
|
||||
|
|
@ -710,9 +709,11 @@ class AnsibleModule(object):
|
|||
required_if=None):
|
||||
|
||||
'''
|
||||
common code for quickly building an ansible module in Python
|
||||
(although you can write modules in anything that can return JSON)
|
||||
see library/* for examples
|
||||
Common code for quickly building an ansible module in Python
|
||||
(although you can write modules with anything that can return JSON).
|
||||
|
||||
See :ref:`developing_modules_general` for a general introduction
|
||||
and :ref:`developing_program_flow_modules` for more detailed explanation.
|
||||
'''
|
||||
|
||||
self._name = os.path.basename(__file__) # initialize name until we can parse from options
|
||||
|
|
@ -2178,11 +2179,12 @@ class AnsibleModule(object):
|
|||
|
||||
def get_bin_path(self, arg, required=False, opt_dirs=None):
|
||||
'''
|
||||
find system executable in PATH.
|
||||
Optional arguments:
|
||||
- required: if executable is not found and required is true, fail_json
|
||||
- opt_dirs: optional list of directories to search in addition to PATH
|
||||
if found return full path; otherwise return None
|
||||
Find system executable in PATH.
|
||||
|
||||
:param arg: The executable to find.
|
||||
:param required: if executable is not found and required is ``True``, fail_json
|
||||
:param opt_dirs: optional list of directories to search in addition to ``PATH``
|
||||
:returns: if found return full path; otherwise return None
|
||||
'''
|
||||
|
||||
bin_path = None
|
||||
|
|
@ -2194,7 +2196,7 @@ class AnsibleModule(object):
|
|||
return bin_path
|
||||
|
||||
def boolean(self, arg):
|
||||
''' return a bool for the arg '''
|
||||
'''Convert the argument to a boolean'''
|
||||
if arg is None:
|
||||
return arg
|
||||
|
||||
|
|
|
|||
|
|
@ -63,12 +63,22 @@ _DEFAULT_PERM = 0o0666 # default file permission bits
|
|||
|
||||
|
||||
def is_executable(path):
|
||||
'''is the given path executable?
|
||||
# This function's signature needs to be repeated
|
||||
# as the first line of its docstring.
|
||||
# This method is reused by the basic module,
|
||||
# the repetion helps the basic module's html documentation come out right.
|
||||
# http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_docstring_signature
|
||||
'''is_executable(path)
|
||||
|
||||
is the given path executable?
|
||||
|
||||
:arg path: The path of the file to check.
|
||||
|
||||
Limitations:
|
||||
|
||||
* Does not account for FSACLs.
|
||||
* Most times we really want to know "Can the current user execute this
|
||||
file" This function does not tell us that, only if an execute bit is set.
|
||||
file". This function does not tell us that, only if any execute bit is set.
|
||||
'''
|
||||
# These are all bitfields so first bitwise-or all the permissions we're
|
||||
# looking for, then bitwise-and with the file's mode to determine if any
|
||||
|
|
|
|||
Loading…
Reference in a new issue