ansible · acozine · Apr 4, 2019 · Feb 27, 2019 · Mar 28, 2019
diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst
@@ -47,16 +47,12 @@ Ansible releases a new major release of Ansible approximately three to four time
 
 .. toctree::
    :glob:
-   :maxdepth: 2
-   :caption: Scenario Guides
-
-   scenario_guides/guide_*
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Ansible for VMWare
+   :maxdepth: 1
+   :caption: Common Ansible Scenarios
 
-   vmware/index
+   scenario_guides/cloud_guides
+   scenario_guides/network_guides
+   scenario_guides/virt_guides
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/docsite/rst/scenario_guides/cloud_guides.rst b/docs/docsite/rst/scenario_guides/cloud_guides.rst
@@ -0,0 +1,21 @@
+.. _cloud_guides:
+
+*******************
+Public Cloud Guides
+*******************
+
+The guides in this section cover using Ansible with a range of public cloud platforms. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.
+
+.. toctree::
+   :maxdepth: 1
+
+   guide_alicloud
+   guide_aws
+   guide_cloudstack
+   guide_gce
+   guide_azure
+   guide_online
+   guide_packet
+   guide_rax
+   guide_scaleway
+   guide_vultr
diff --git a/docs/docsite/rst/scenario_guides/guide_docker.rst b/docs/docsite/rst/scenario_guides/guide_docker.rst
@@ -1,5 +1,5 @@
-Getting Started with Docker
-===========================
+Docker Guide
+============
 
 Ansible offers the following modules for orchestrating Docker containers:
 
@@ -327,7 +327,3 @@ For the default host and each host in the hosts list define the following attrib
      description: The port containers use for SSH
      required: false
      default: 22
-
-
-
-
diff --git a/docs/docsite/rst/scenario_guides/guide_kubernetes.rst b/docs/docsite/rst/scenario_guides/guide_kubernetes.rst
@@ -1,5 +1,5 @@
-Getting Started with Kubernetes and OpenShift
-=============================================
+Kubernetes and OpenShift Guide
+==============================
 
 Modules for interacting with the Kubernetes (K8s) and OpenShift API are under development, and can be used in preview mode. To use them, review the requirements, and then follow the installation and use instructions.
 
@@ -53,4 +53,3 @@ Filing issues
 If you find a bug or have a suggestion regarding individual modules or the role, please file issues at `OpenShift Rest Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.
 
 There is also a utility module, k8s_common.py, that is part of the `Ansible <https://github.com/ansible/ansible>`_ repo. If you find a bug or have suggestions regarding it, please file issues at `Ansible issues <https://github.com/ansible/ansible/issues>`_.
-
diff --git a/docs/docsite/rst/scenario_guides/guide_online.rst b/docs/docsite/rst/scenario_guides/guide_online.rst
@@ -1,6 +1,6 @@
-*************************
-Using Ansible with Online
-*************************
+****************
+Online.net Guide
+****************
 
 Introduction
 ============

diff --git a/docs/docsite/rst/scenario_guides/guide_scaleway.rst b/docs/docsite/rst/scenario_guides/guide_scaleway.rst
@@ -1,8 +1,8 @@
 .. _guide_scaleway:
 
-***************************
-Using Scaleway with Ansible
-***************************
+**************
+Scaleway Guide
+**************
 
 .. _scaleway_introduction:
 

diff --git a/docs/docsite/rst/scenario_guides/guide_vagrant.rst b/docs/docsite/rst/scenario_guides/guide_vagrant.rst
@@ -1,5 +1,5 @@
-Using Vagrant and Ansible
-=========================
+Vagrant Guide
+=============
 
 .. _vagrant_intro:
 
@@ -151,4 +151,3 @@ The "Tips and Tricks" chapter of the `Ansible Provisioner documentation
         The open issues for the Ansible provisioner in the Vagrant project
     :ref:`working_with_playbooks`
         An introduction to playbooks
-
diff --git a/docs/docsite/rst/scenario_guides/guide_vmware.rst b/docs/docsite/rst/scenario_guides/guide_vmware.rst
@@ -0,0 +1,30 @@
+.. _vmware_ansible:
+
+******************
+VMware Guide
+******************
+
+Welcome to the Ansible for VMware Guide!
+
+The purpose of this guide is to teach you everything you need to know about using Ansible with VMware.
+
+To get started, please select one of the following topics.
+
+.. toctree::
+   :maxdepth: 1
+
+   vmware_scenarios/vmware_intro
+   vmware_scenarios/vmware_concepts
+   vmware_scenarios/vmware_requirements
+   vmware_scenarios/vmware_inventory
+   vmware_scenarios/vmware_scenarios
+   vmware_scenarios/vmware_troubleshooting
+   vmware_scenarios/vmware_external_doc_links
+   vmware_scenarios/faq
+.. comments look like this - start with two dots
+.. getting_started content not ready
+.. vmware_scenarios/vmware_getting_started
+.. module index page not ready
+.. vmware_scenarios/vmware_module_reference
+.. always exclude the template file
+.. vmware_scenarios/vmware_scenario_1
diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst
@@ -1,15 +1,42 @@
 :orphan:
 
-***************
+.. unified index page included for backwards compatibility
+
+******************
 Scenario Guides
-***************
+******************
+
+The guides in this section cover integrating Ansible with a variety of
+platforms, products, and technologies. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Public Cloud Guides
 
-The guides in this section explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.
+   guide_alicloud
+   guide_aws
+   guide_cloudstack
+   guide_gce
+   guide_azure
+   guide_online
+   guide_packet
+   guide_rax
+   guide_scaleway
+   guide_vultr
 
 .. toctree::
-   :glob:
    :maxdepth: 1
+   :caption: Network Technology Guides
+
+   guide_aci
+   guide_meraki
+   guide_infoblox
 
-   guide_*
+.. toctree::
+   :maxdepth: 1
+   :caption: Virtualization & Containerization Guides
 
-Pending topics may include: Jenkins, Linode/DigitalOcean, Continuous Deployment, and more.
+   guide_docker
+   guide_kubernetes
+   guide_vagrant
+   guide_vmware
diff --git a/docs/docsite/rst/scenario_guides/network_guides.rst b/docs/docsite/rst/scenario_guides/network_guides.rst
@@ -0,0 +1,16 @@
+.. _network_guides:
+
+*************************
+Network Technology Guides
+*************************
+
+The guides in this section cover using Ansible with specific network technologies. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.
+
+.. toctree::
+   :maxdepth: 1
+
+   guide_aci
+   guide_meraki
+   guide_infoblox
+
+To learn more about Network Automation with Ansible, see :ref:`network_getting_started` and :ref:`network_advanced`.
diff --git a/docs/docsite/rst/scenario_guides/virt_guides.rst b/docs/docsite/rst/scenario_guides/virt_guides.rst
@@ -0,0 +1,15 @@
+.. _virtualization_guides:
+
+******************************************
+Virtualization and Containerization Guides
+******************************************
+
+The guides in this section cover integrating Ansible with popular tools for creating virtual machines and containers. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features.
+
+.. toctree::
+   :maxdepth: 1
+
+   guide_docker
+   guide_kubernetes
+   guide_vagrant
+   guide_vmware
diff --git a/docs/docsite/rst/vmware/faq.rst → .../scenario_guides/vmware_scenarios/faq.rst b/docs/docsite/rst/vmware/faq.rst → .../scenario_guides/vmware_scenarios/faq.rst
diff --git a/...te/rst/vmware/scenario_clone_template.rst → ...are_scenarios/scenario_clone_template.rst b/...te/rst/vmware/scenario_clone_template.rst → ...are_scenarios/scenario_clone_template.rst
diff --git a/...te/rst/vmware/scenario_find_vm_folder.rst → ...are_scenarios/scenario_find_vm_folder.rst b/...te/rst/vmware/scenario_find_vm_folder.rst → ...are_scenarios/scenario_find_vm_folder.rst
diff --git a/...docsite/rst/vmware/scenario_remove_vm.rst → ...s/vmware_scenarios/scenario_remove_vm.rst b/...docsite/rst/vmware/scenario_remove_vm.rst → ...s/vmware_scenarios/scenario_remove_vm.rst
diff --git a/...docsite/rst/vmware/scenario_rename_vm.rst → ...s/vmware_scenarios/scenario_rename_vm.rst b/...docsite/rst/vmware/scenario_rename_vm.rst → ...s/vmware_scenarios/scenario_rename_vm.rst
diff --git a/...csite/rst/vmware/scenario_vmware_http.rst → ...vmware_scenarios/scenario_vmware_http.rst b/...csite/rst/vmware/scenario_vmware_http.rst → ...vmware_scenarios/scenario_vmware_http.rst
diff --git a/docs/docsite/rst/vmware/vmware_concepts.rst → ...ides/vmware_scenarios/vmware_concepts.rst b/docs/docsite/rst/vmware/vmware_concepts.rst → ...ides/vmware_scenarios/vmware_concepts.rst
@@ -4,9 +4,10 @@
 Ansible for VMware Concepts
 ***************************
 
-These concepts are common to all uses of Ansible, including VMware automation. You need to understand them to use Ansible for VMware automation. This basic introduction provides the background you need to follow the examples in this guide.
+Some of these concepts are common to all uses of Ansible, including VMware automation; some are specific to VMware. You need to understand them to use Ansible for VMware automation. This introduction provides the background you need to follow the :ref:`scenarios<vmware_scenarios>` in this guide.
 
-.. contents:: Topics
+.. contents::
+   :local:
 
 Control Node
 ============
@@ -16,20 +17,18 @@ Any machine with Ansible installed. You can run commands and playbooks, invoking
 Delegation
 ==========
 
-If you want to perform a VMware specific task on one host with reference to ESXi server or vCenter server, use the ``delegate_to`` keyword on a task. This delegation host will be any host where you have ``pyVmomi`` installed. Your control node and ``delegate_to`` host can be same or different.
+Delegation allows you to select the system that executes a given task. If you do not have ``pyVmomi`` installed on your control node, use the ``delegate_to`` keyword on VMware-specific tasks to execute them on any host where you have ``pyVmomi`` installed.
 
 Modules
 =======
 
-The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches on vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of VMware modules<vmware_cloud_modules>`.
-
+The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches in the vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of cloud modules<cloud_modules>`, which includes VMware modules.
 
 Playbooks
 =========
 
 Ordered lists of tasks, saved so you can run those tasks in that order repeatedly. Playbooks can include variables as well as tasks. Playbooks are written in YAML and are easy to read, write, share and understand.
 
-
 pyVmomi
 =======
 

diff --git a/.../rst/vmware/vmware_external_doc_links.rst → ...e_scenarios/vmware_external_doc_links.rst b/.../rst/vmware/vmware_external_doc_links.rst → ...e_scenarios/vmware_external_doc_links.rst
@@ -1,10 +1,8 @@
 .. _vmware_external_doc_links:
 
-******************************
-List of useful links to VMware
-******************************
-
-Following is the list of various external documentation and guides which can helpful in further readings.
+*****************************
+Other useful VMware resources
+*****************************
 
 * `PyVmomi Documentation <https://github.com/vmware/pyvmomi/tree/master/docs>`_
 * `VMware API and SDK Documentation <https://www.vmware.com/support/pubs/sdk_pubs.html>`_

diff --git a/...ite/rst/vmware/vmware_getting_started.rst → ...ware_scenarios/vmware_getting_started.rst b/...ite/rst/vmware/vmware_getting_started.rst → ...ware_scenarios/vmware_getting_started.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _vmware_ansible_getting_started:
 
 ***************************************

diff --git a/docs/docsite/rst/vmware/vmware_intro.rst → ..._guides/vmware_scenarios/vmware_intro.rst b/docs/docsite/rst/vmware/vmware_intro.rst → ..._guides/vmware_scenarios/vmware_intro.rst
diff --git a/docs/docsite/rst/vmware/vmware_inventory.rst → ...des/vmware_scenarios/vmware_inventory.rst b/docs/docsite/rst/vmware/vmware_inventory.rst → ...des/vmware_scenarios/vmware_inventory.rst
diff --git a/...te/rst/vmware/vmware_module_reference.rst → ...are_scenarios/vmware_module_reference.rst b/...te/rst/vmware/vmware_module_reference.rst → ...are_scenarios/vmware_module_reference.rst
@@ -1,7 +1,9 @@
+:orphan:
+
 .. _vmware_ansible_module_index:
 
 ***************************
 Ansible VMware Module Guide
 ***************************
 
-This will be a listing similar to the module index in our core docs.
+This will be a listing similar to the module index in our core docs.
diff --git a/...ocsite/rst/vmware/vmware_requirements.rst → .../vmware_scenarios/vmware_requirements.rst b/...ocsite/rst/vmware/vmware_requirements.rst → .../vmware_scenarios/vmware_requirements.rst
@@ -4,28 +4,22 @@
 VMware Prerequisites
 ********************
 
-.. contents:: Topics
+.. contents::
+   :local:
 
+Installing SSL Certificates
+===========================
 
-Installing SSL Certificate
-==========================
+All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication. You must enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node.
 
-All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication.
+If the SSL certificate of your vCenter or ESXi server is not correctly installed on your Ansible control node, you will see the following warning when using Ansible VMware modules:
 
-If you see the following warning while using Ansible VMware modules [warning], you need to enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node.
+``Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)``
 
-```
-Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)
-```
+To install the SSL certificate for your VMware server,  and run your Ansible VMware modules in encrypted mode, please follow the instructions for the server you are running with VMware.
 
-then, this means you need to add/install SSL certificate of vCenter or ESXi server in your Ansible control node.
-
-The following instructions allow you to run your Ansible VMware modules with encrypted mode (viz. ``validate_certs=True``).
-
-Please follow the instructions depending upon your server to install SSL certificate.
-
-vCenter
--------
+Installing vCenter SSL certificates for Ansible
+-----------------------------------------------
 
 * From any web browser, go to the base URL of the vCenter Server without port number like ``https://vcenter-domain.example.com``
 
@@ -38,9 +32,8 @@ vCenter
 * Install the certificate files are trusted certificates by the process that is appropriate for your operating system.
 
 
-
-ESXi
-----
+Installing ESXi SSL certificates for Ansible
+--------------------------------------------
 
 * Enable SSH Service on ESXi either by using Ansible VMware module `vmware_host_service_manager <https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/vmware/vmware_host_config_manager.py>`_ or manually using vSphere Web interface.
 

diff --git a/.../docsite/rst/vmware/vmware_scenario_1.rst → ...es/vmware_scenarios/vmware_scenario_1.rst b/.../docsite/rst/vmware/vmware_scenario_1.rst → ...es/vmware_scenarios/vmware_scenario_1.rst
@@ -1,4 +1,4 @@
-.. _vmware_scenario_1:
+:orphan:
 
 **********************************
 Sample Scenario for Ansible VMware

diff --git a/docs/docsite/rst/vmware/vmware_scenarios.rst → ...des/vmware_scenarios/vmware_scenarios.rst b/docs/docsite/rst/vmware/vmware_scenarios.rst → ...des/vmware_scenarios/vmware_scenarios.rst
@@ -4,21 +4,13 @@
 Ansible for VMware Scenarios
 ****************************
 
-Welcome to the Ansible for VMWare Guide!
-
-The purpose of this guide is to teach you everything you need to know about using Ansible with VMWare.
-
-To get started, please select one of the following topics.
-
+These scenarios teach you how to accomplish common VMware tasks using Ansible. To get started, please select the task you want to accomplish.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    scenario_clone_template
    scenario_rename_vm
    scenario_remove_vm
    scenario_find_vm_folder
    scenario_vmware_http
-   vmware_scenario_1
-
-