adds stub API docs in a single file (#46663)

* adds stub API docs in a single file

docs/docsite/rst/api/index.rst

@@ -0,0 +1,103 @@
+:orphan:
+
+*************************
+Ansible API Documentation
+*************************
+
+The Ansible API is under construction. These stub references will be documented in future.
+
+.. contents::
+   :local:
+
+Attributes
+==========
+
+.. py:attribute:: AnsibleModule.params
+
+The parameters accepted by the module.
+
+.. py:attribute:: ansible.module_utils.basic.ANSIBLE_VERSION
+
+.. py:attribute:: ansible.module_utils.basic.SELINUX_SPECIAL_FS
+
+Deprecated in favor of ansibleModule._selinux_special_fs.
+
+.. py:attribute:: AnsibleModule.ansible_version
+
+.. py:attribute:: AnsibleModule._debug
+
+.. py:attribute:: AnsibleModule._diff
+
+.. py:attribute:: AnsibleModule.no_log
+
+.. py:attribute:: AnsibleModule._selinux_special_fs
+
+(formerly ansible.module_utils.basic.SELINUX_SPECIAL_FS)
+
+.. py:attribute:: AnsibleModule._syslog_facility
+
+.. py:attribute:: self.playbook
+
+.. py:attribute:: self.play
+
+.. py:attribute:: self.task
+
+.. py:attribute:: sys.path
+
+
+Classes
+=======
+
+.. py:class:: ansible.module_utils.basic.AnsibleModule
+
+The basic utilities for AnsibleModule.
+
+.. py:class:: AnsibleModule
+
+The main class for an Ansible module.
+
+
+Functions
+=========
+
+.. py:function:: ansible.module_utils.basic._load_params()
+
+Load parameters.
+
+
+Methods
+=======
+
+.. py:method:: AnsibleModule.log()
+
+Logs the output of Ansible.
+
+.. py:method:: AnsibleModule.debug()
+
+Debugs Ansible.
+
+.. py:method:: Ansible.get_bin_path()
+
+Retrieves the path for executables.
+
+.. py:method:: AnsibleModule.run_command()
+
+Runs a command within an Ansible module.
+
+.. py:method:: module.fail_json()
+
+Exits and returns a failure.
+
+.. py:method:: module.exit_json()
+
+Exits and returns output.
+
+
+Modules
+=======
+
+.. py:module:: ansible.module_utils
+
+.. py:module:: ansible.module_utils.basic
+
+.. py:module:: ansible.module_utils.url

docs/docsite/rst/dev_guide/debugging.rst

@@ -110,11 +110,11 @@ When you look into the debug_dir you'll see a directory structure like this::
 
 * The :file:`ansible` directory contains code from
   :mod:`ansible.module_utils` that is used by the module.  Ansible includes
-  files for any :`module:`ansible.module_utils` imports in the module but not
+  files for any :mod:`ansible.module_utils` imports in the module but not
   any files from any other module.  So if your module uses
   :mod:`ansible.module_utils.url` Ansible will include it for you, but if
-  your module includes :mod:`requests` then you'll have to make sure that
-  the python requests library is installed on the system before running the
+  your module includes `requests <http://docs.python-requests.org/en/master/api/>`_ then you'll have to make sure that
+  the python `requests library <https://pypi.org/project/requests/>`_ is installed on the system before running the
   module.  You can modify files in this directory if you suspect that the
   module is having a problem in some of this boilerplate code rather than in
   the module code you have written.
@@ -139,7 +139,7 @@ module file and test that the real module works via :command:`ansible` or
     The wrapper provides one more subcommand, ``excommunicate``.  This
     subcommand is very similar to ``execute`` in that it invokes the exploded
     module on the arguments in the :file:`args`.  The way it does this is
-    different, however.  ``excommunicate`` imports the :func:`main`
+    different, however.  ``excommunicate`` imports the ``main``
     function from the module and then calls that.  This makes excommunicate
     execute the module in the wrapper's process.  This may be useful for
     running the module under some graphical debuggers but it is very different

docs/docsite/rst/dev_guide/developing_modules_best_practices.rst

@@ -44,7 +44,7 @@ Python tips
 
 * When fetching URLs, use ``fetch_url`` or ``open_url`` from ``ansible.module_utils.urls``. Do not use ``urllib2``, which does not natively verify TLS certificates and so is insecure for https.
 * Include a ``main`` function that wraps the normal execution.
-* Call your :func:`main` from a conditional so you can import it into unit tests - for example:
+* Call your ``main`` function from a conditional so you can import it into unit tests - for example:
 
 	.. code-block:: python
 

docs/docsite/rst/dev_guide/developing_python_3.rst

@@ -68,15 +68,15 @@ they can be an array of text.  Text is what we think of as letters, digits,
 numbers, other printable symbols, and a small number of unprintable "symbols"
 (control codes).
 
-In Python 2, the two types for these (:class:`str` for bytes and
-:class:`unicode` for text) are often used interchangeably.  When dealing only
+In Python 2, the two types for these (:class:`str <python:str>` for bytes and
+:func:`unicode <python:unicode>` for text) are often used interchangeably.  When dealing only
 with ASCII characters, the strings can be combined, compared, and converted
 from one type to another automatically.  When non-ASCII characters are
 introduced, Python 2 starts throwing exceptions due to not knowing what encoding
 the non-ASCII characters should be in.
 
-Python 3 changes this behavior by making the separation between bytes (:class:`bytes`)
-and text (:class:`str`) more strict.  Python 3 will throw an exception when
+Python 3 changes this behavior by making the separation between bytes (:class:`bytes <python3:bytes>`)
+and text (:class:`str <python3:str>`) more strict.  Python 3 will throw an exception when
 trying to combine and compare the two types.  The programmer has to explicitly
 convert from one type to the other to mix values from each.
 
@@ -95,7 +95,7 @@ Controller string strategy: the Unicode Sandwich
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In controller-side code we use a strategy known as the Unicode Sandwich (named
-after Python 2's :class:`unicode` text type).  For Unicode Sandwich we know that
+after Python 2's :func:`unicode  <python:unicode>` text type).  For Unicode Sandwich we know that
 at the border of our code and the outside world (for example, file and network IO,
 environment variables, and some library calls) we are going to receive bytes.
 We need to transform these bytes into text and use that throughout the
@@ -189,7 +189,7 @@ to the filesystem, it can be more convenient to transform to bytes right away
 and manipulate in bytes.
 
 .. warning:: Make sure all variables passed to a function are the same type.
-    If you're working with something like :func:`os.path.join` which takes
+    If you're working with something like :func:`python3:os.path.join` which takes
     multiple strings and uses them in combination, you need to make sure that
     all the types are the same (either all bytes or all text).  Mixing
     bytes and text will cause tracebacks.
@@ -271,17 +271,17 @@ to make certain constructs act the same way on Python 2 and Python 3:
     __metaclass__ = type
 
 ``__metaclass__ = type`` makes all classes defined in the file into new-style
-classes without explicitly inheriting from :class:`object`.
+classes without explicitly inheriting from :class:`object <python3:object>`.
 
 The ``__future__`` imports do the following:
 
-:absolute_import: Makes imports look in :attr:`sys.path` for the modules being
+:absolute_import: Makes imports look in :data:`sys.path <python3:sys.path>` for the modules being
     imported, skipping the directory in which the module doing the importing
     lives.  If the code wants to use the directory in which the module doing
     the importing, there's a new dot notation to do so.
 :division: Makes division of integers always return a float.  If you need to
    find the quotient use ``x // y`` instead of ``x / y``.
-:print_function: Changes :func:`print` from a keyword into a function.
+:print_function: Changes :func:`print <python3:print>` from a keyword into a function.
 
 .. seealso::
     * `PEP 0328: Absolute Imports <https://www.python.org/dev/peps/pep-0328/#guido-s-decision>`_

docs/docsite/rst/dev_guide/testing/sanity/use-argspec-type-path.rst

@@ -5,7 +5,6 @@ The AnsibleModule argument_spec knows of several types beyond the standard pytho
 these is ``path``.  When used, type ``path`` ensures that an argument is a string and expands any
 shell variables and tilde characters.
 
-This test looks for use of :meth:`os.path.expanduser` in modules.  When found, it tells the user to
+This test looks for use of :func:`os.path.expanduser <python:os.path.expanduser>` in modules.  When found, it tells the user to
 replace it with ``type='path'`` in the module's argument_spec or list it as a false positive in the
 test.
-