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