Pull documentation of ansible.module_utils.basic from (improved) doc strings. (#48416)

docs/docsite/rst/api/index.rst

@@ -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.
 

docs/docsite/rst/conf.py

@@ -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'
 

docs/docsite/rst/reference_appendices/.rstcheck.cfg

@@ -0,0 +1,2 @@
+[rstcheck]
+ignore_directives=autoclass,automodule

docs/docsite/rst/reference_appendices/module_utils.rst

@@ -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
+To use this functionality, include ``from ansible.module_utils.basic import AnsibleModule`` in your module.
-      Utilities in module_utils.basic.AnsibleModule apply to all module types
 
-    .. _AnsibleModule.debug:
+.. autoclass:: ansible.module_utils.basic.AnsibleModule
-    AnsibleModule.debug
+   :members:
-    .. _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)
 
 
-.. _ansible.module_utils.basic:
-
 Basic
 ------
-.. glossary::
 
-    ansible.module_utils.basic
+To use this functionality, include ``import ansible.module_utils.basic`` in your module.
-      Utilities in module_utils.basic apply to all module types.
 
-    .. _ansible.module_utils.basic.SELINUX_SPECIAL_FS:
+.. automodule:: ansible.module_utils.basic
-    ansible.module_utils.basic.SELINUX_SPECIAL_FS
+   :members:
-      *deprecated* replaced by :term:`ansible.module_utils.basic.AnsibleModule._selinux_special_fs`
-
-    .. _ansible.module_utils.basic._load_params:
-    load_params

lib/ansible/module_utils/basic.py

@@ -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
+    Convert number in string format into bytes (ex: '2K' => 2048) or using unit argument.
-    ex:
+    example: human_to_bytes('10M') <=> human_to_bytes(10, 'M')
-      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
+        Common code for quickly building an ansible module in Python
-        (although you can write modules in anything that can return JSON)
+        (although you can write modules with anything that can return JSON).
-        see library/* for examples
+
+        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.
+        Find system executable in PATH.
-        Optional arguments:
+
-           - required:  if executable is not found and required is true, fail_json
+        :param arg: The executable to find.
-           - opt_dirs:  optional list of directories to search in addition to PATH
+        :param required: if executable is not found and required is ``True``, fail_json
-        if found return full path; otherwise return None
+        :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
 

lib/ansible/module_utils/common/file.py

@@ -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