Fix Docs build issues (#22295)

* restore network docs fragments

* Fix RST errors

* code-block formatting

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -35,7 +35,9 @@ ANSIBLE_METADATA Block
 
 ANSIBLE_METADATA contains information about the module for use by other tools. At the moment, it informs other tools which type of maintainer the module has and to what degree users can rely on a module's behaviour remaining the same over time.
 
-For new modules, the following block can be simply added into your module::
+For new modules, the following block can be simply added into your module
+
+.. code-block:: python
 
    ANSIBLE_METADATA = {'status': ['preview'],
                        'supported_by': 'community',
@@ -55,7 +57,7 @@ Version 1.0 of the metadata
 Structure
 `````````
 
-Format::
+.. code-block:: python
 
   ANSIBLE_METADATA = {
       'version': '1.0',
@@ -298,11 +300,11 @@ built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory.
 
 To test your documentation against your ``argument_spec`` you can use ``validate-modules``. Note that this option isn't currently enabled in Shippable due to the time it takes to run.
 
-.. code-block:: shell-session
+.. code-block:: bash
 
    # If you don't already, ensure you are using your local checkout
-   $ source hacking/env-setup
+   source hacking/env-setup
-   $ ./test/sanity/validate-modules/validate-modules --arg-spec --warnings  lib/ansible/modules/your/modules/
+   ./test/sanity/validate-modules/validate-modules --arg-spec --warnings  lib/ansible/modules/your/modules/
 
 .. tip::
 

docs/docsite/rst/dev_guide/developing_modules_in_groups.rst

@@ -3,10 +3,9 @@ Information for submitting a group of modules
 
 .. contents:: Topics
 
-.. _module_dev_welcome:
+Submitting a group of modules
+`````````````````````````````
 
-Welcome
-```````
 This section discusses how to get multiple related modules into Ansible.
 
 This document is intended for both companies wishing to add modules for their own products as well as users of 3rd party products wishing to add Ansible functionality.
@@ -60,7 +59,7 @@ Where to get support
 
 Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered.
 
-On :doc:`community` you can find how to:
+On :doc:`../community` you can find how to:
 
 * Subscribe to the Mailing Lists - We suggest "Ansible Development List" (for codefreeze info) and "Ansible Announce list"
 * ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNodes IRC network works best for module developers so we can have an interactive dialogue.
@@ -92,7 +91,7 @@ And that's it.
 
 Before pushing your PR to GitHub it's a good idea to review the :doc:`developing_modules_checklist` again.
 
-After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`YAMLSyntax`) or code that isn't valid Python 2.4 & Python 2.6 (see :doc:`developing_modules_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
+After publishing your PR to https://github.com/ansible/ansible, a Shippable CI test should run within a few minutes. Check the results (at the end of the PR page) to ensure that it's passing (green). If it's not passing, inspect each of the results. Most of the errors should be self-explanatory and are often related to badly formatted documentation (see :doc:`../YAMLSyntax`) or code that isn't valid Python 2.4 & Python 2.6 (see :doc:`developing_modules_python3`). If you aren't sure what a Shippable test message means, copy it into the PR along with a comment and we will review.
 
 If you need further advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
 

docs/docsite/rst/playbooks_lookups.rst

@@ -105,7 +105,7 @@ To enter comma use two commas ',,' somewhere - preferably at the end. Quotes and
 .. _passwordstore_lookup:
 
 The Passwordstore Lookup
-```````````````````
+````````````````````````
 .. versionadded:: 2.3
 
 The ``passwordstore`` lookup enables Ansible to retrieve, create or update passwords from

docs/docsite/rst/roadmap/ROADMAP_2_3.rst

@@ -84,9 +84,10 @@ Target: February/March 2017
   - For 2.3:
 
     - We want all tests to pass
+
       - Just the mercurial tests left because we haven't created an image with
         both python2 and python3 to test it on yet.
-      - Check by doing ``grep skip/python3 test/integration/targets/\*/aliases``
+      - Check by doing ``grep skip/python3 test/integration/targets/*/aliases``
     - If users report bugs on python3, these should be fixed and will prioritize our work on porting other modules.
   - Still have to solve the python3-only and python2-only modules.  Thinking of doing this via metadata.  Will mean we have to use metadata at the module_common level.  Will also mean we don’t support py2-only or py3-only old style python modules.
   - Note: Most of the currently tested ansible features now run.  But there’s still a lot of code that’s untested.

lib/ansible/utils/module_docs_fragments/eos.py

@@ -0,0 +1,112 @@
+#
+# (c) 2015, Peter Sprygada <psprygada@ansible.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    # Standard files documentation fragment
+    DOCUMENTATION = """
+options:
+  host:
+    description:
+      - Specifies the DNS host name or address for connecting to the remote
+        device over the specified transport.  The value of host is used as
+        the destination address for the transport.
+    required: true
+  port:
+    description:
+      - Specifies the port to use when building the connection to the remote
+        device.  This value applies to either I(cli) or I(eapi).  The port
+        value will default to the appropriate transport common port if
+        none is provided in the task.  (cli=22, http=80, https=443).
+    required: false
+    default: 0 (use common port)
+  username:
+    description:
+      - Configures the username to use to authenticate the connection to
+        the remote device.  This value is used to authenticate
+        either the CLI login or the eAPI authentication depending on which
+        transport is used. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
+    required: false
+  password:
+    description:
+      - Specifies the password to use to authenticate the connection to
+        the remote device.  This is a common argument used for either I(cli)
+        or I(eapi) transports. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
+    required: false
+    default: null
+  timeout:
+    description:
+      - Specifies the timeout in seconds for communicating with the network device
+        for either connecting or sending commands.  If the timeout is
+        exceeded before the operation is completed, the module will error.
+    require: false
+    default: 10
+  ssh_keyfile:
+    description:
+      - Specifies the SSH keyfile to use to authenticate the connection to
+        the remote device.  This argument is only used for I(cli) transports.
+        If the value is not specified in the task, the value of environment
+        variable C(ANSIBLE_NET_SSH_KEYFILE) will be used instead.
+    required: false
+  authorize:
+    description:
+      - Instructs the module to enter privileged mode on the remote device
+        before sending any commands.  If not specified, the device will
+        attempt to execute all commands in non-privileged mode. If the value
+        is not specified in the task, the value of environment variable
+        C(ANSIBLE_NET_AUTHORIZE) will be used instead.
+    required: false
+    default: no
+    choices: ['yes', 'no']
+  auth_pass:
+    description:
+      - Specifies the password to use if required to enter privileged mode
+        on the remote device.  If I(authorize) is false, then this argument
+        does nothing. If the value is not specified in the task, the value of
+        environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
+    required: false
+    default: none
+  transport:
+    description:
+      - Configures the transport connection to use when connecting to the
+        remote device.
+    required: true
+    choices:
+        - eapi
+        - cli
+    default: cli
+  use_ssl:
+    description:
+      - Configures the I(transport) to use SSL if set to true only when the
+        C(transport=eapi).  If the transport
+        argument is not eapi, this value is ignored.
+    required: false
+    default: yes
+    choices: ['yes', 'no']
+  provider:
+    description:
+      - Convenience method that allows all I(eos) arguments to be passed as
+        a dict object.  All constraints (required, choices, etc) must be
+        met either by individual arguments or values in this dict.
+    required: false
+    default: null
+
+"""

lib/ansible/utils/module_docs_fragments/ios.py

@@ -0,0 +1,92 @@
+#
+# (c) 2015, Peter Sprygada <psprygada@ansible.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    # Standard files documentation fragment
+    DOCUMENTATION = """
+options:
+  host:
+    description:
+      - Specifies the DNS host name or address for connecting to the remote
+        device over the specified transport.  The value of host is used as
+        the destination address for the transport.
+    required: true
+  port:
+    description:
+      - Specifies the port to use when building the connection to the remote.
+        device.
+    required: false
+    default: 22
+  username:
+    description:
+      - Configures the username to use to authenticate the connection to
+        the remote device.  This value is used to authenticate
+        the SSH session. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
+    required: false
+  password:
+    description:
+      - Specifies the password to use to authenticate the connection to
+        the remote device.   This value is used to authenticate
+        the SSH session. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
+    required: false
+    default: null
+  timeout:
+    description:
+      - Specifies the timeout in seconds for communicating with the network device
+        for either connecting or sending commands.  If the timeout is
+        exceeded before the operation is completed, the module will error.
+    require: false
+    default: 10
+  ssh_keyfile:
+    description:
+      - Specifies the SSH key to use to authenticate the connection to
+        the remote device.   This value is the path to the
+        key used to authenticate the SSH session. If the value is not specified
+        in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
+        will be used instead.
+    required: false
+  authorize:
+    description:
+      - Instructs the module to enter privileged mode on the remote device
+        before sending any commands.  If not specified, the device will
+        attempt to execute all commands in non-privileged mode. If the value
+        is not specified in the task, the value of environment variable
+        C(ANSIBLE_NET_AUTHORIZE) will be used instead.
+    required: false
+    default: no
+    choices: ['yes', 'no']
+  auth_pass:
+    description:
+      - Specifies the password to use if required to enter privileged mode
+        on the remote device.  If I(authorize) is false, then this argument
+        does nothing. If the value is not specified in the task, the value of
+        environment variable C(ANSIBLE_NET_AUTH_PASS) will be used instead.
+    required: false
+    default: none
+  provider:
+    description:
+      - Convenience method that allows all I(ios) arguments to be passed as
+        a dict object.  All constraints (required, choices, etc) must be
+        met either by individual arguments or values in this dict.
+    required: false
+    default: null
+"""

lib/ansible/utils/module_docs_fragments/iosxr.py

@@ -0,0 +1,74 @@
+#
+# (c) 2015, Peter Sprygada <psprygada@ansible.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    # Standard files documentation fragment
+    DOCUMENTATION = """
+options:
+  host:
+    description:
+      - Specifies the DNS host name or address for connecting to the remote
+        device over the specified transport.  The value of host is used as
+        the destination address for the transport.
+    required: true
+  port:
+    description:
+      - Specifies the port to use when building the connection to the remote.
+        device.
+    required: false
+    default: 22
+  username:
+    description:
+      - Configures the username to use to authenticate the connection to
+        the remote device.  This value is used to authenticate
+        the SSH session. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
+    required: false
+  password:
+    description:
+      - Specifies the password to use to authenticate the connection to
+        the remote device.   This value is used to authenticate
+        the SSH session. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
+    required: false
+    default: null
+  timeout:
+    description:
+      - Specifies the timeout in seconds for communicating with the network device
+        for either connecting or sending commands.  If the timeout is
+        exceeded before the operation is completed, the module will error.
+    require: false
+    default: 10
+  ssh_keyfile:
+    description:
+      - Specifies the SSH key to use to authenticate the connection to
+        the remote device.   This value is the path to the
+        key used to authenticate the SSH session. If the value is not specified
+        in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
+        will be used instead.
+    required: false
+  provider:
+    description:
+      - Convenience method that allows all I(iosxr) arguments to be passed as
+        a dict object.  All constraints (required, choices, etc) must be
+        met either by individual arguments or values in this dict.
+    required: false
+    default: null
+"""

lib/ansible/utils/module_docs_fragments/vyos.py

@@ -0,0 +1,75 @@
+#
+# (c) 2015, Peter Sprygada <psprygada@ansible.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+class ModuleDocFragment(object):
+
+    # Standard files documentation fragment
+    DOCUMENTATION = """
+options:
+  host:
+    description:
+      - Specifies the DNS host name or address for connecting to the remote
+        device over the specified transport.  The value of host is used as
+        the destination address for the transport.
+    required: true
+  port:
+    description:
+      - Specifies the port to use when building the connection to the remote
+        device.
+    required: false
+    default: 22
+  username:
+    description:
+      - Configures the username to use to authenticate the connection to
+        the remote device.  This value is used to authenticate
+        the SSH session. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_USERNAME) will be used instead.
+    required: false
+  password:
+    description:
+      - Specifies the password to use to authenticate the connection to
+        the remote device.   This value is used to authenticate
+        the SSH session. If the value is not specified in the task, the
+        value of environment variable C(ANSIBLE_NET_PASSWORD) will be used instead.
+    required: false
+    default: null
+  timeout:
+    description:
+      - Specifies the timeout in seconds for communicating with the network device
+        for either connecting or sending commands.  If the timeout is
+        exceeded before the operation is completed, the module will error.
+    require: false
+    default: 10
+  ssh_keyfile:
+    description:
+      - Specifies the SSH key to use to authenticate the connection to
+        the remote device.   This value is the path to the
+        key used to authenticate the SSH session. If the value is not specified
+        in the task, the value of environment variable C(ANSIBLE_NET_SSH_KEYFILE)
+        will be used instead.
+    required: false
+  provider:
+    description:
+      - Convenience method that allows all I(vyos) arguments to be passed as
+        a dict object.  All constraints (required, choices, etc) must be
+        met either by individual arguments or values in this dict.
+    required: false
+    default: null
+
+"""