Upgrade the rst convention of the Reference Guide [4]

We upgrade the rst convention by following Documentation Contributor
Guide[1].

[1] https://docs.openstack.org/doc-contrib-guide

Change-Id: I0e4184e24210f920ea5e7b33e4878385a0758a01
Implements: blueprint optimize-the-documentation-format

doc/source/reference/skydive-guide.rst

@@ -5,7 +5,7 @@ Skydive in Kolla
 ================
 
 Overview
-========
+~~~~~~~~
 Skydive is an open source real-time network topology and protocols analyzer.
 It aims to provide a comprehensive way of understanding what is happening in
 the network infrastructure.
@@ -16,13 +16,15 @@ All the information is stored in an Elasticsearch database.
 Configuration on Kolla deployment
 ---------------------------------
 
-Enable Skydive in ``/etc/kolla/globals.yml``
+Enable Skydive in ``/etc/kolla/globals.yml`` file:
 
-.. code-block:: console
+.. code-block:: yaml
 
    enable_skydive: "yes"
    enable_elasticsearch: "yes"
 
+.. end
+
 Verify operation
 ----------------
 

doc/source/reference/swift-guide.rst

@@ -5,12 +5,13 @@ Swift in Kolla
 ==============
 
 Overview
-========
+~~~~~~~~
+
 Kolla can deploy a full working Swift setup in either a **all-in-one** or
 **multinode** setup.
 
 Disks with a partition table (recommended)
-==========================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Swift requires block devices to be available for storage. To prepare a disk
 for use as a Swift storage device, a special partition name and filesystem
@@ -19,9 +20,12 @@ label need to be added.
 The following should be done on each storage node, the example is shown
 for three disks:
 
-::
+.. warning::
+
+   ALL DATA ON DISK will be LOST!
+
+.. code-block:: console
 
-    # <WARNING ALL DATA ON DISK will be LOST!>
    index=0
    for d in sdc sdd sde; do
        parted /dev/${d} -s -- mklabel gpt mkpart KOLLA_SWIFT_DATA 1 -1
@@ -29,9 +33,11 @@ for three disks:
        (( index++ ))
    done
 
+.. end
+
 For evaluation, loopback devices can be used in lieu of real disks:
 
-::
+.. code-block:: console
 
    index=0
    for d in sdc sdd sde; do
@@ -43,8 +49,10 @@ For evaluation, loopback devices can be used in lieu of real disks:
        (( index++ ))
    done
 
+.. end
+
 Disks without a partition table
-===============================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Kolla also supports unpartitioned disk (filesystem on ``/dev/sdc`` instead of
 ``/dev/sdc1``) detection purely based on filesystem label. This is generally
@@ -54,13 +62,15 @@ deployment already using disk like this.
 Given hard disks with labels swd1, swd2, swd3, use the following settings in
 ``ansible/roles/swift/defaults/main.yml``.
 
-::
+.. code-block:: yaml
 
    swift_devices_match_mode: "prefix"
    swift_devices_name: "swd"
 
+.. end
+
 Rings
-=====
+~~~~~
 
 Before running Swift we need to generate **rings**, which are binary compressed
 files that at a high level let the various Swift services know where data is in
@@ -71,14 +81,27 @@ generate rings for a demo setup.  The commands work with **disks with partition
 table** example listed above. Please modify accordingly if your setup is
 different.
 
-::
+Prepare for Rings generating
+---------------------------- 
+
+To perpare for Swift Rings generating, run the following commands to initialize
+the environment variable and create ``/etc/kolla/config/swift`` directory:
+
+.. code-block:: console
 
    STORAGE_NODES=(192.168.0.2 192.168.0.3 192.168.0.4)
    KOLLA_SWIFT_BASE_IMAGE="kolla/oraclelinux-source-swift-base:4.0.0"
-
    mkdir -p /etc/kolla/config/swift
 
-  # Object ring
+.. end
+
+Generate Object Ring
+--------------------
+
+To generate Swift object ring, run the following commands:
+
+.. code-block:: console
+
    docker run \
      --rm \
      -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \
@@ -97,7 +120,15 @@ different.
        done
    done
 
-  # Account ring
+.. end
+
+Generate Account Ring
+---------------------
+
+To generate Swift account ring, run the following commands:
+
+.. code-block:: console
+
    docker run \
      --rm \
      -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \
@@ -116,7 +147,15 @@ different.
        done
    done
 
-  # Container ring
+.. end
+
+Generate Container Ring
+-----------------------
+
+To generate Swift container ring, run the following commands:
+
+.. code-block:: console
+
    docker run \
      --rm \
      -v /etc/kolla/config/swift/:/etc/kolla/config/swift/ \
@@ -144,31 +183,40 @@ different.
          /etc/kolla/config/swift/${ring}.builder rebalance;
    done
 
-For more info, see
+.. end
+
+For more information, see
 https://docs.openstack.org/project-install-guide/object-storage/ocata/initial-rings.html
 
 Deploying
-=========
+~~~~~~~~~
+
 Enable Swift in ``/etc/kolla/globals.yml``:
 
-::
+.. code-block:: yaml
 
    enable_swift : "yes"
 
+.. end
+
 Once the rings are in place, deploying Swift is the same as any other Kolla
 Ansible service:
 
-::
+.. code-block:: console
 
-  kolla-ansible deploy -i <path/to/inventory-file>
+   # kolla-ansible deploy -i <path/to/inventory-file>
+
+.. end
+
+Verification
+~~~~~~~~~~~~
 
-Validation
-==========
 A very basic smoke test:
 
-::
+.. code-block:: console
 
    $ openstack container create mycontainer
+
    +---------------------------------------+--------------+------------------------------------+
    | account                               | container    | x-trans-id                         |
    +---------------------------------------+--------------+------------------------------------+
@@ -176,6 +224,7 @@ A very basic smoke test:
    +---------------------------------------+--------------+------------------------------------+
 
    $ openstack object create mycontainer README.rst
+
    +---------------+--------------+----------------------------------+
    | object        | container    | etag                             |
    +---------------+--------------+----------------------------------+
@@ -183,6 +232,7 @@ A very basic smoke test:
    +---------------+--------------+----------------------------------+
 
    $ openstack container show mycontainer
+
    +--------------+---------------------------------------+
    | Field        | Value                                 |
    +--------------+---------------------------------------+
@@ -193,6 +243,7 @@ A very basic smoke test:
    +--------------+---------------------------------------+
 
    $ openstack object store account show
+
    +------------+---------------------------------------+
    | Field      | Value                                 |
    +------------+---------------------------------------+

doc/source/reference/tacker-guide.rst

@@ -1,14 +1,16 @@
+===============
 Tacker in Kolla
 ===============
 
-"Tacker is an OpenStack service for NFV Orchestration with
+"Tacker is an OpenStack service for NFV Orchestration with a general purpose
-a general purpose VNF Manager to deploy and operate
+VNF Manager to deploy and operate Virtual Network Functions (VNFs) and
-Virtual Network Functions (VNFs) and Network Services
+Network Services on an NFV Platform. It is based on ETSI MANO Architectural
-on an NFV Platform.
+Framework."
-It is based on ETSI MANO Architectural Framework." [1].
+For more details about Tacker, see `OpenStack Tacker Documentation
+<https://docs.openstack.org/tacker/latest/>`__.
 
 Overview
---------
+~~~~~~~~
 
 As of the Pike release, tacker requires the following services
 to be enabled to operate correctly.
@@ -26,7 +28,7 @@ Optionally tacker supports the following services and features.
 * Opendaylight
 
 Compatibility
--------------
+~~~~~~~~~~~~~
 
 Tacker is supported by the following distros and install_types.
 
@@ -39,7 +41,7 @@ Tacker is supported by the following distros and install_types.
   * Only source images.
 
 Preparation and Deployment
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default tacker and required services are disabled in
 the ``group_vars/all.yml`` file.
@@ -50,13 +52,15 @@ In order to enable them, you need to edit the file
 
    Heat is enabled by default, ensure it is not disabled.
 
-::
+.. code-block:: yaml
 
    enable_tacker: "yes"
    enable_barbican: "yes"
    enable_mistral: "yes"
    enable_redis: "yes"
 
+.. end
+
 .. warning::
 
    Barbican is required in multinode deployments to share VIM fernet_keys.
@@ -66,31 +70,39 @@ In order to enable them, you need to edit the file
 
 Deploy tacker and related services.
 
-::
+.. code-block:: console
 
    $ kolla-ansible deploy
 
-Verify
+.. end
-------
+
+Verification
+~~~~~~~~~~~~
 
 Generate the credentials file.
 
-::
+.. code-block:: console
 
    $ kolla-ansible post-deploy
 
+.. end
+
 Source credentials file.
 
-::
+.. code-block:: console
 
    $ . /etc/kolla/admin-openrc.sh
 
+.. end
+
 Create base neutron networks and glance images.
 
-::
+.. code-block:: console
 
    $ sh tools/init-runonce
 
+.. end
+
 .. note::
 
    ``init-runonce`` file is located in ``$PYTHON_PATH/kolla-ansible``
@@ -107,16 +119,20 @@ Install python-tackerclient.
    Barbican, heat and mistral python clients are in tacker's
    requirements and will be installed as dependency.
 
-::
+.. code-block:: console
 
    $ pip install python-tackerclient
 
+.. end
+
 Execute ``deploy-tacker-demo`` script to initialize the VNF creation.
 
-::
+.. code-block:: console
 
    $ sh deploy-tacker-demo
 
+.. end
+
 Tacker demo script will create sample VNF Descriptor (VNFD) file,
 then register a default VIM, create a tacker VNFD and finally
 deploy a VNF from the previously created VNFD.
@@ -127,42 +143,51 @@ running in nova and with its corresponding heat stack CREATION_COMPLETE.
 
 Verify tacker VNF status is ACTIVE.
 
-::
+.. code-block:: console
 
    $ tacker vnf-list
+
    +--------------------------------------+------------------+-----------------------+--------+--------------------------------------+--------------------------------------+
    | id                                   | name             | mgmt_url              | status | vim_id                               | vnfd_id                              |
    +--------------------------------------+------------------+-----------------------+--------+--------------------------------------+--------------------------------------+
    | c52fcf99-101d-427b-8a2d-c9ef54af8b1d | kolla-sample-vnf | {"VDU1": "10.0.0.10"} | ACTIVE | eb3aa497-192c-4557-a9d7-1dff6874a8e6 | 27e8ea98-f1ff-4a40-a45c-e829e53b3c41 |
    +--------------------------------------+------------------+-----------------------+--------+--------------------------------------+--------------------------------------+
 
+.. end
+
 Verify nova instance status is ACTIVE.
 
-::
+.. code-block:: console
 
    $ openstack server list
+
    +--------------------------------------+-------------------------------------------------------+--------+--------------------+--------+-----------------------------------------------------------------------------------------------------------------------+
    | ID                                   | Name                                                  | Status | Networks           | Image  | Flavor                                                                                                                |
    +--------------------------------------+-------------------------------------------------------+--------+--------------------+--------+-----------------------------------------------------------------------------------------------------------------------+
    | d2d59eeb-8526-4826-8f1b-c50b571395e2 | ta-cf99-101d-427b-8a2d-c9ef54af8b1d-VDU1-fchiv6saay7p | ACTIVE | demo-net=10.0.0.10 | cirros | tacker.vnfm.infra_drivers.openstack.openstack_OpenStack-c52fcf99-101d-427b-8a2d-c9ef54af8b1d-VDU1_flavor-yl4bzskwxdkn |
    +--------------------------------------+-------------------------------------------------------+--------+--------------------+--------+-----------------------------------------------------------------------------------------------------------------------+
 
+.. end
+
 Verify Heat stack status is CREATE_COMPLETE.
 
-::
+.. code-block:: console
 
    $ openstack stack list
+
    +--------------------------------------+----------------------------------------------------------------------------------------------+----------------------------------+-----------------+----------------------+--------------+
    | ID                                   | Stack Name                                                                                   | Project                          | Stack Status    | Creation Time        | Updated Time |
    +--------------------------------------+----------------------------------------------------------------------------------------------+----------------------------------+-----------------+----------------------+--------------+
    | 289a6686-70f6-4db7-aa10-ed169fe547a6 | tacker.vnfm.infra_drivers.openstack.openstack_OpenStack-c52fcf99-101d-427b-8a2d-c9ef54af8b1d | 1243948e59054aab83dbf2803e109b3f | CREATE_COMPLETE | 2017-08-23T09:49:50Z | None         |
    +--------------------------------------+----------------------------------------------------------------------------------------------+----------------------------------+-----------------+----------------------+--------------+
 
+.. end
+
 After the correct functionality of tacker is verified, tacker demo
 can be cleaned up executing ``cleanup-tacker`` script.
 
-::
+.. code-block:: console
 
    $ sh cleanup-tacker
 
-[1] https://docs.openstack.org/tacker/latest/
+.. end

doc/source/reference/vmware-guide.rst

@@ -1,11 +1,12 @@
 .. _vmware-guide:
 
-====================
+===============
 VMware in Kolla
-====================
+===============
 
 Overview
-========
+~~~~~~~~
+
 Kolla can deploy the Nova and Neutron Service(s) for VMware vSphere.
 Depending on the network architecture (NsxV or DVS) you choose, Kolla deploys
 the following OpenStack services for VMware vSphere:
@@ -46,7 +47,7 @@ bridge and works through VLAN.
    attach to Provider VLAN/Flat networks.
 
 VMware NSX-V
-============
+~~~~~~~~~~~~
 
 Preparation
 -----------
@@ -62,7 +63,7 @@ For more information, please see `VMware NSX-V documentation <https://docs.vmwar
 
    On every VMware host, edit /etc/vmware/firewall/vnc.xml as below:
 
-.. code-block:: console
+.. code-block:: none
 
    <!-- FirewallRule for VNC Console -->
    <ConfigRoot>
@@ -91,17 +92,23 @@ For more information, please see `VMware NSX-V documentation <https://docs.vmwar
    </service>
    </ConfigRoot>
 
+.. end
+
 Then refresh the firewall config by:
 
 .. code-block:: console
 
-    esxcli network firewall refresh
+   # esxcli network firewall refresh
+
+.. end
 
 Verify that the firewall config is applied:
 
 .. code-block:: console
 
-    esxcli network firewall ruleset list
+   # esxcli network firewall ruleset list
+
+.. end
 
 Deployment
 ----------
@@ -109,15 +116,17 @@ Deployment
 Enable VMware nova-compute plugin and NSX-V neutron-server plugin in
 ``/etc/kolla/globals.yml``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    nova_compute_virt_type: "vmware"
    neutron_plugin_agent: "vmware_nsxv"
 
+.. end
+
 .. note::
 
    VMware NSX-V also supports Neutron FWaaS, LBaaS and VPNaaS services, you can enable
-    them by setting these options in globals.yml:
+   them by setting these options in ``globals.yml``:
 
    * enable_neutron_vpnaas: "yes"
    * enable_neutron_lbaas: "yes"
@@ -126,27 +135,31 @@ Enable VMware nova-compute plugin and NSX-V neutron-server plugin in
 If you want to set VMware datastore as cinder backend, enable it in
 ``/etc/kolla/globals.yml``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    enable_cinder: "yes"
    cinder_backend_vmwarevc_vmdk: "yes"
    vmware_datastore_name: "TestDatastore"
 
+.. end
+
 If you want to set VMware datastore as glance backend, enable it in
 ``/etc/kolla/globals.yml``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    glance_backend_vmware: "yes"
    vmware_vcenter_name: "TestDatacenter"
    vmware_datastore_name: "TestDatastore"
 
+.. end
+
 VMware options are required in ``/etc/kolla/globals.yml``, these options should
 be configured correctly according to your NSX-V environment.
 
-Options for nova-compute and ceilometer:
+Options for ``nova-compute`` and ``ceilometer``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    vmware_vcenter_host_ip: "127.0.0.1"
    vmware_vcenter_host_username: "admin"
@@ -154,17 +167,21 @@ Options for nova-compute and ceilometer:
    vmware_vcenter_insecure: "True"
    vmware_vcenter_datastore_regex: ".*"
 
+.. end
+
 .. note::
 
    The VMware vCenter password has to be set in ``/etc/kolla/passwords.yml``.
 
-    .. code-block:: console
+   .. code-block:: yaml
 
       vmware_vcenter_host_password: "admin"
 
+   .. end
+
 Options for Neutron NSX-V support:
 
-.. code-block:: console
+.. code-block:: yaml
 
    vmware_nsxv_user: "nsx_manager_user"
    vmware_nsxv_manager_uri: "https://127.0.0.1"
@@ -180,6 +197,8 @@ Options for Neutron NSX-V support:
    vmware_nsxv_metadata_initializer: "false"
    vmware_nsxv_edge_ha: "false"
 
+.. yaml
+
 .. note::
 
    If you want to set secure connections to VMware, set ``vmware_vcenter_insecure``
@@ -191,15 +210,17 @@ Options for Neutron NSX-V support:
 
    The VMware NSX-V password has to be set in ``/etc/kolla/passwords.yml``.
 
-     .. code-block:: console
+   .. code-block:: yaml
 
       vmware_nsxv_password: "nsx_manager_password"
 
-Then you should start kolla-ansible deployment normally as KVM/QEMU deployment.
+   .. end
+
+Then you should start :command:`kolla-ansible` deployment normally as KVM/QEMU deployment.
 
 
 VMware NSX-DVS
-==============
+~~~~~~~~~~~~~~
 
 Preparation
 -----------
@@ -216,29 +237,35 @@ Deployment
 Enable VMware nova-compute plugin and NSX-V neutron-server plugin in
 ``/etc/kolla/globals.yml``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    nova_compute_virt_type: "vmware"
    neutron_plugin_agent: "vmware_dvs"
 
+.. end
+
 If you want to set VMware datastore as Cinder backend, enable it in
 ``/etc/kolla/globals.yml``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    enable_cinder: "yes"
    cinder_backend_vmwarevc_vmdk: "yes"
    vmware_datastore_name: "TestDatastore"
 
+.. end
+
 If you want to set VMware datastore as Glance backend, enable it in
 ``/etc/kolla/globals.yml``:
 
-.. code-block:: console
+.. code-block:: yaml
 
    glance_backend_vmware: "yes"
    vmware_vcenter_name: "TestDatacenter"
    vmware_datastore_name: "TestDatastore"
 
+.. end
+
 VMware options are required in ``/etc/kolla/globals.yml``, these options should
 be configured correctly according to the vSphere environment you installed
 before. All option for nova, cinder, glance are the same as VMware-NSX, except
@@ -246,7 +273,7 @@ the following options.
 
 Options for Neutron NSX-DVS support:
 
-.. code-block:: console
+.. code-block:: yaml
 
    vmware_dvs_host_ip: "192.168.1.1"
    vmware_dvs_host_port: "443"
@@ -254,15 +281,19 @@ Options for Neutron NSX-DVS support:
    vmware_dvs_dvs_name: "VDS-1"
    vmware_dvs_dhcp_override_mac: ""
 
+.. end
+
 .. note::
 
    The VMware NSX-DVS password has to be set in ``/etc/kolla/passwords.yml``.
 
-     .. code-block:: console
+   .. code-block:: yaml
 
       vmware_dvs_host_password: "password"
 
-Then you should start kolla-ansible deployment normally as KVM/QEMU deployment.
+   .. end
+
+Then you should start :command:`kolla-ansible` deployment normally as KVM/QEMU deployment.
 
 For more information on OpenStack vSphere, see
 `VMware vSphere

doc/source/reference/zun-guide.rst

@@ -1,9 +1,12 @@
+============
 Zun in Kolla
 ============
 
 "Zun is an OpenStack Container service. It aims to provide an
 OpenStack API for provisioning and managing containerized
-workload on OpenStack." [1].
+workload on OpenStack."
+For more details about Zun, see `OpenStack Zun Documentation
+<https://docs.openstack.org/zun/latest/>`__.
 
 Preparation and Deployment
 --------------------------
@@ -14,10 +17,12 @@ configure kuryr refer to :doc:`kuryr-guide`.
 To allow Zun Compute connect to the Docker Daemon, add the following in the
 ``docker.service`` file on each zun-compute node.
 
-::
+.. code-block:: none
 
    ExecStart= -H tcp://<DOCKER_SERVICE_IP>:2375 -H unix:///var/run/docker.sock --cluster-store=etcd://<DOCKER_SERVICE_IP>:2379 --cluster-advertise=<DOCKER_SERVICE_IP>:2375
 
+.. end
+
 .. note::
 
    ``DOCKER_SERVICE_IP`` is zun-compute host IP address. ``2375`` is port that
@@ -27,77 +32,96 @@ By default zun is disabled in the ``group_vars/all.yml``.
 In order to enable it, you need to edit the file globals.yml and set the
 following variables:
 
-::
+.. code-block:: yaml
 
    enable_zun: "yes"
    enable_kuryr: "yes"
    enable_etcd: "yes"
 
+.. end
+
 Deploy the OpenStack cloud and zun.
 
-::
+.. code-block:: console
 
    $ kolla-ansible deploy
 
-Verify
+.. end
-------
 
-Generate the credentials file.
+Verification
+------------
 
-::
+#. Generate the credentials file:
+
+   .. code-block:: console
 
       $ kolla-ansible post-deploy
 
-Source credentials file.
+   .. end
 
-::
+#. Source credentials file:
+
+   .. code-block:: console
 
       $ . /etc/kolla/admin-openrc.sh
 
-Download and create a glance container image.
+   .. end
 
-::
+#. Download and create a glance container image:
+
+   .. code-block:: console
 
       $ docker pull cirros
       $ docker save cirros | openstack image create cirros --public \
         --container-format docker --disk-format raw
 
-Create zun container.
+   .. end
 
-::
+#. Create zun container:
+
+   .. code-block:: console
 
       $ zun create --name test --net network=demo-net cirros ping -c4 8.8.8.8
 
+   .. end
+
    .. note::
 
       Kuryr does not support networks with DHCP enabled, disable DHCP in the
       subnet used for zun containers.
 
-  ::
+      .. code-block:: console
 
-    openstack subnet set --no-dhcp <subnet>
+         $ openstack subnet set --no-dhcp <subnet>
 
-Verify container is created.
+      .. end
 
-::
+#. Verify container is created:
+
+   .. code-block:: console
 
       $ zun list
+
       +--------------------------------------+------+---------------+---------+------------+------------+-------+
       | uuid                                 | name | image         | status  | task_state | addresses  | ports |
       +--------------------------------------+------+---------------+---------+------------+------------+-------+
       | 3719a73e-5f86-47e1-bc5f-f4074fc749f2 | test | cirros        | Created | None       | 172.17.0.3 | []    |
       +--------------------------------------+------+---------------+---------+------------+------------+-------+
 
-Start container.
+   .. end
 
-::
+#. Start container:
+
+   .. code-block:: console
 
       $ zun start test
       Request to start container test has been accepted.
 
-Verify container.
+   .. end
 
-::
+#. Verify container:
+
+   .. code-block:: console
 
       $ zun logs test
       PING 8.8.8.8 (8.8.8.8): 56 data bytes
@@ -110,5 +134,7 @@ Verify container.
       4 packets transmitted, 4 packets received, 0% packet loss
       round-trip min/avg/max = 95.884/96.376/96.721 ms
 
+   .. end
+
 For more information about how zun works, see
 `zun, OpenStack Container service <https://docs.openstack.org/zun/latest/>`__.