Fix rst formatting and fix tox

This patch does 2 things:
1) it fixes the broken formatting of all of the rst files, so they
   render correctly through sphinx
2) Fix tox so that it runs cleanly against the corrected rst files.

Change-Id: I3b3689c61054f051075dc6bc519c02e4c63626f7

requirements.txt

@@ -4,3 +4,4 @@ pbr>=0.6,<1.0
 sphinx>=1.1.2,<1.2
 testrepository>=0.0.18
 testtools>=0.9.34
+flake8

specs/juno/affinity-antiaffinity-filter.rst

@@ -4,9 +4,9 @@
 
  http://creativecommons.org/licenses/by/3.0/legalcode
 
-==========================================
+===========================================
 Affinity and anti-affinity scheduler filter
-==========================================
+===========================================
 
 https://blueprints.launchpad.net/cinder/+spec/affinity-antiaffinity-filter
 

specs/juno/configurable-ssh-host-key-policy.rst

@@ -4,9 +4,9 @@
 
  http://creativecommons.org/licenses/by/3.0/legalcode
 
-==========================================
+=============================================
 Configurable SSH Host Key Policies for Cinder
-==========================================
+=============================================
 
 Include the URL of your launchpad blueprint:
 

specs/juno/consistency-groups.rst

@@ -77,8 +77,8 @@ Consistency Groups work flow
     and sends request to Cinder volume node.
 
   * Cinder manager calls novaclient which calls a new Nova admin API "quiesce"
-that uses QEMU guest agent to freeze the guest filesystem. Can leverage this
+    that uses QEMU guest agent to freeze the guest filesystem. Can leverage
-work:
+    this work:
     https://wiki.openstack.org/wiki/Cinder/QuiescedSnapshotWithQemuGuestAgent
     (Note: This step will be on hold for now because the freeze feature is not
     reliable yet.)
@@ -88,8 +88,8 @@ reliable yet.)
   * Cinder driver communicates with backend array to create a point-in-time
     consistency snapshot of the CG.
 
-  * Cinder manager calls novaclient which calls a new Nova admin API "unquiesce"
+  * Cinder manager calls novaclient which calls a new Nova admin API
-that uses QEMU guest agent to thaw the guest filesystem.
+    "unquiesce" that uses QEMU guest agent to thaw the guest filesystem.
     (Note: This step will be on hold for now.)
 
 Alternatives
@@ -100,9 +100,9 @@ at the orchestration layer.  However, in that case, Cinder wouldn't know which
 volumes are belonging to a CG.  As a result, user can delete a volume belonging
 to the CG using Cinder CLI or Horizon without knowing the consequences.
 
-Another alternative is not to implement CG at all.  User will be able to operate
+Another alternative is not to implement CG at all.  User will be able to
-at individual volume level, but can't provide crash consistent data protection of
+operate at individual volume level, but can't provide crash consistent data
-multiple volumes in the same application.
+protection of multiple volumes in the same application.
 
 Data model impact
 -----------------
@@ -122,6 +122,7 @@ consistencygroup uuid.
 * snapshot entries in snapshots table will have a foreign key of the
   cgsnapshot uuid.
 
+::
 
  mysql> desc cgsnapshots;
  +---------------------+--------------+------+-----+---------+-------+

specs/juno/huawei-dsware-driver.rst

@@ -35,7 +35,7 @@ so we also add a new connector to realize attach/detach volume.
 
 The following diagram shows the command and data paths.
 
-````
+::
 
                     +------------------+
                     |                  |
@@ -71,7 +71,6 @@ The following diagram shows the command and data paths.
                     +------------------+
 
 
-````
 
 Add new driver in /cinder/volume/drivers path, and realize cinder driver
 minimum features:

specs/juno/huawei-sdshypervisor-driver.rst

@@ -59,7 +59,7 @@ protocal, so we also add a new connector to realize attach/detach volume.
 
 The following diagram shows the command and data paths.
 
-````
+::
 
                     +------------------+
                     |                  |
@@ -95,7 +95,6 @@ The following diagram shows the command and data paths.
                     +------------------+
 
 
-````
 
 Add new driver in /cinder/volume/drivers path, and realize cinder driver
 minimum features:

specs/juno/hyper-v-smbfs-volume-driver.rst

@@ -4,9 +4,9 @@
 
  http://creativecommons.org/licenses/by/3.0/legalcode
 
-=================
+=========================
 Windows SMB Volume Driver
-=================
+=========================
 
 https://blueprints.launchpad.net/cinder/+spec/hyper-v-smbfs-volume-driver
 
@@ -96,9 +96,10 @@ Certain volume related operations will require to be synchronized.
 Other deployer impact
 ---------------------
 
-The user will provide a list of SMB shares on which volumes may reside. This list
+The user will provide a list of SMB shares on which volumes may reside. This
-will be placed in a file located at a path configured in the cinder config file.
+list will be placed in a file located at a path configured in the cinder config
-This share list may contain SMB mount options such as flags or credentials.
+file.  This share list may contain SMB mount options such as flags or
+credentials.
 
 The config file will also contain the path to the Samba config file. Oversubmit
 and used space ratios may also be configured.

specs/juno/incremental-backup.rst

@@ -1,11 +1,9 @@
-Proposal to implement incremental backup feature in Cinder
+..
-
  This work is licensed under a Creative Commons Attribution 3.0 Unported
  License.
+
  http://creativecommons.org/licenses/by/3.0/legalcode
 
-This specification proposes two new options to cinder-backup create api to
-support incremental backup and backup from a volume snapshot.
 
 ========================================
 Support for incremental backup in Cinder
@@ -13,7 +11,7 @@ Support for incremental backup in Cinder
 Launchpad Blueprint:
   https://blueprints.launchpad.net/cinder/+spec/incremental-backup
 
-Problem description:
+Problem description
 ====================
 The current implementation of Cinder Backup functionality only supports full
 backup and restore of a given volume. There is no provision to backup changes
@@ -23,7 +21,7 @@ entire volumes during backups will be resource intensive and do not scale well
 for larger deployments. This specification discusses implementation of
 incremental backup feature in detail.
 
-Proposed change:
+Proposed change
 ================
 Cinder backup API, by default uses Swift as its backend. When a volume is
 backed up to Swift, Swift creates a manifest file that describes the contents
@@ -70,6 +68,8 @@ contains a reference to the full backup container.
 
 Following changes are made to the manifest header of the backup
 
+::
+
         metadata['version'] = self.DRIVER_VERSION
         metadata['backup_id'] = backup['id']
         metadata['volume_id'] = volume_id
@@ -92,8 +92,8 @@ of the full volume from the full backup copy and then apply incremental
 changes at offset and length as described in the incremental backup manifest.
 
 
-Snapshot based backups
+Snapshot based backups::
-======================
+
  Since existing backup implementation copies the data directly from the volume,
  it requires the volume to be detached from the instance. For most cloud
  workloads this may be sufficient but other workloads that cannot tolerate
@@ -109,7 +109,7 @@ more simpler than backup API taking snapshot of the volume and then managing
  the snapshots.
 
 Alternatives
-============
+------------
 Incremental backup offers two important benefits:
  1. Use less storage when storing backup images
  2. Use less network bandwidth and improve overall efficiency of backup process
@@ -121,15 +121,17 @@ second benefit cannot be achieved unless Cinder backup supports incremental
 backup.
 
 Data model impact
-=================
+-----------------
 No percieved data model changes
 
 REST API impact
-===============
+---------------
 No new APIs are proposed. Instead existing backup API will be enhanced to
 accept additional option called "--incr" with <path to full backup container>"
 as its argument.
 
+::
+
  cinder backup-create <volumeid> --incr <full backup container>
    Performs incremental backup
 
@@ -145,15 +147,15 @@ snapshot
 No anticipated changes to restore api
 
 Security impact
-===============
+---------------
 None
 
 Notifications impact
-====================
+--------------------
 None
 
 Other end user impact
-=====================
+---------------------
 python-cinderclient will be modified to accept "--incr" option. It may
 include some validation code to validate if the full backup container path
 is valid
@@ -163,7 +165,7 @@ it happens, the dashboard will provide an option for user to choose incremental
 backup
 
 Performance Impact
-==================
+------------------
 Except for calculating SHAs during full backup operation, there is no other
 performance impact on existing API. The performance penalty can be easily
 offset by the efficiency gained by incremental backup. Also new hardware
@@ -171,18 +173,19 @@ support CPU instructions to calculate SHAs which alleviates some stress on
 the CPU cycles.
 
 Other deployer impact
-=====================
+---------------------
 None
 
 
 Developer impact
-================
+----------------
 None
 
 Implementation
 ==============
 
 Assignee(s)
+-----------
 Primary assignee:
 muralibalcha(murali.balcha@triliodata.com)
 
@@ -190,7 +193,7 @@ Other contributors:
 giribasava(giri.basava@triliodata.com)
 
 Work Items
-==========
+----------
 1. python-cinderclient
    That accepts "--incr" option and some validation code
 
@@ -208,20 +211,24 @@ Work Items
 
 Dependencies
 ============
+
 None
 
 Testing
 =======
+
 Unit tests will be added for incremental backup.
 
 Testing will primarily focus on the following:
  1. SHA file generation
  2. Creating various changes to the original volume. These include
+
   1. Changes to first block
   2. Changes to last block
   3. Changes to odd number of successive blocks
   4. Changes to even number of successive blocks
   5. Changes spread across multiple sections of the volume
+
  3. Perform 1 incremental
  4. Peform multiple incremental backups
  5. Restore series of incremental backups and compare the contents
@@ -230,5 +237,10 @@ Testing will primarily focus on the following:
 
 Documentation Impact
 ====================
+
 Need to document new option in the block storage manual.
 
+References
+==========
+
+None

specs/juno/log-translation-hints.rst

@@ -25,6 +25,9 @@ Proposed change
 
 Since there are too many files need to change, so divide this bp into 16
 patches according to cinder directories.
+
+::
+
 	├─cinder
 	│  ├─api
 	│  ├─backup
@@ -53,6 +56,11 @@ removing translation of debug msgs.
 That work is being addressed by the following spec/blueprint:
 https://review.openstack.org/#/c/100338/
 
+Alternatives
+------------
+
+None
+
 Data model impact
 -----------------
 
@@ -110,6 +118,9 @@ For each directory's files, we change all the log messages as follows.
  4. Change "LOG.critical(_(" to "LOG.info(_LC(".
 
 We handle these changes in the following order:
+
+::
+
 	cinder
 	cinder/api
 	cinder/backup
@@ -130,6 +141,9 @@ We handle these changes in the following order:
 Add a HACKING check rule to ensure that log messages to relative domain.
 Using regular expression to check whether log messages with relative _L*
 function.
+
+ .. code-block:: python
+
 	log_translation_domain_error = re.compile(
 		r"(.)*LOG\.error\(\s*\_LE('|\")")
 	log_translation_domain_warning = re.compile(
@@ -157,6 +171,6 @@ None
 References
 ==========
 
-[1]https://blueprints.launchpad.net/oslo/+spec/log-messages-translation-domain-rollout
+.. [#] https://blueprints.launchpad.net/oslo/+spec/log-messages-translation-domain-rollout
-[2]https://review.openstack.org/#/c/70455
+.. [#] https://review.openstack.org/#/c/70455
-[3]https://wiki.openstack.org/wiki/LoggingStandards
+.. [#] https://wiki.openstack.org/wiki/LoggingStandards

specs/juno/pool-aware-cinder-scheduler.rst

@@ -154,6 +154,8 @@ flexibility, developer should update their drivers to include all sub-pool
 capacities and capabilities in the volume stats it reports to scheduler.
 Below is an example of new stats message:
 
+.. code-block:: python
+
         {
             'volume_backend_name': 'Local iSCSI', #\
             'vendor_name': 'OpenStack',           #  backend level
@@ -193,6 +195,10 @@ Below is an example of new stats message:
             ]
         }
 
+
+Implementation
+==============
+
 Assignee(s)
 -----------
 

specs/juno/private-volume-types.rst

@@ -59,6 +59,8 @@ Database schema changes:
   table for every volume_type_id and project_id combination.
   It will be a many-to-many relationship.
 
+::
+
   mysql> DESC volume_types;
   +--------------+--------------+------+-----+---------+-------+
   | Field        | Type         | Null | Key | Default | Extra |

specs/juno/smbfs-volume-driver.rst

@@ -97,15 +97,16 @@ retrieve informations such as free space or total allocated space.
 
 Certain volume related operations will require to be synchronized.
 
-In order to use local shares, the share paths will be read from the Samba config
+In order to use local shares, the share paths will be read from the Samba
-file.
+config file.
 
 Other deployer impact
 ---------------------
 
-The user will provide a list of SMB shares on which volumes may reside. This list
+The user will provide a list of SMB shares on which volumes may reside. This
-will be placed in a file located at a path configured in the cinder config file.
+list will be placed in a file located at a path configured in the cinder config
-This share list may contain SMB mount options such as flags or credentials.
+file.  This share list may contain SMB mount options such as flags or
+credentials.
 
 The config file will also contain the path to the Samba config file. Oversubmit
 and used space ratios may also be configured.

specs/juno/support-reset-state-for-backup.rst

@@ -27,16 +27,18 @@ bp is to another mean for administrators to solve these problems by calling
 backup reset state API.
 
 1. Resetting status from creating/restoring to available
+
  1) restoring --> available
     Directly change the backup status to 'error', because the backup data is
     already existed in storage backend.
  2) creating --> available
-Use backup-create routine as an example to illustrate what benefit we can get
+    Use backup-create routine as an example to illustrate what benefit we can
-from backup-reset function. Backup-create routine first backup volume and
+    get from backup-reset function. Backup-create routine first backup volume
-metadatas, and then update the status of volume and backup. If database just
+    and metadatas, and then update the status of volume and backup. If database
-went down after update the volume's status to 'available', leaving the
+    just went down after update the volume's status to 'available', leaving the
-backup's status to be 'creating' without having methods to deal with through
+    backup's status to be 'creating' without having methods to deal with
-API.
+    through API.
+
  If we have reset-state API and resetting status from creating to available, we
  first verify whether the backup is ok on storage backend.
  If so, we change backup status from creating to available.
@@ -59,6 +61,9 @@ Alternatives
 
 Login in the cinder database, use the following update sql to change the
 backup item.
+
+::
+
     update backups set status='some status' where id='xxx-xxx-xxx-xxx';
 
 Data model impact

specs/juno/task-log.rst

@@ -64,6 +64,11 @@ The following suggestion seems to be agreed upon:
 .. _notification: http://docs.openstack.org/developer/taskflow/notifications.html
 .. _log listener: http://docs.openstack.org/developer/taskflow/notifications.html#printing-and-logging-listeners
 
+Alternatives
+------------
+
+N/A
+
 Data model impact
 -----------------
 

specs/juno/unit-test-cases-for-cinder-scripts.rst

@@ -130,7 +130,9 @@ Packagers should be aware of the following changes to setup.cfg.
 cinder uses pbr to handle packaging.  The cinder scripts that is under the
 [files] section will be moved to the [entry_points] section of setup.cfg.
 More specifically, this proposal adds console_scripts to the [entry_points]
-section of setup.cfg as follows::
+section of setup.cfg as follows:
+
+.. code-block:: ini
 
   [entry_points]
   console_scripts =

specs/juno/united-policy.json-in-cinder.rst

@@ -49,6 +49,11 @@ Security impact
 
 None
 
+Notifications impact
+--------------------
+
+None
+
 Other end user impact
 ---------------------
 

specs/juno/valid-states-api.rst

@@ -20,8 +20,8 @@ Problem description
 
 The purpose of this feature is to facilite exposing the reset-state API in
 horizon in a meaningful way by restricting the set of permissible states that
-the administrator can specify for a volume.  There is no API for this, and it is
+the administrator can specify for a volume.  There is no API for this, and it
-undesirable to hardcode this information into horizon.
+is undesirable to hardcode this information into horizon.
 
 Proposed change
 ===============
@@ -73,7 +73,8 @@ Other end user impact
 A new command, get-valid-states, will be added to python-cinderclient.  This
 command mirrors the underlying API function.
 
-Obtaining the list of valid states for a volume or snapshot can be performed by:
+Obtaining the list of valid states for a volume or snapshot can be performed
+by:
 $ cinder get-valid-states
 
 

specs/juno/vhost-support.rst

@@ -72,7 +72,8 @@ Performance Impact
 ------------------
 
 Cinder itself being the control plane will not experience any different
-performance. The data plane should experience a greater deal of performance [1].
+performance. The data plane should experience a greater deal of performance
+[1].
 
 Other deployer impact
 ---------------------

specs/juno/volume-replication.rst

@@ -196,13 +196,16 @@ Replication relationship db table:
 * secondary_id = Column(String(36), ForeignKey('volumes.id'), nullable=False)
 * primary_replication_unit_id = Column(String(255))
 * secondary_replication_unit_id = Column(String(255))
-* status = Column(Enum('error', 'creating', 'copying', 'active', 'active-stopped',
+* status = Column(Enum('error', 'creating', 'copying', 'active',
-                       'stopping', 'deleting', 'deleted', 'inactive',
+                       'active-stopped', 'stopping', 'deleting', 'deleted',
-                       name='replicationrelationship_status'))
+                       'inactive', name='replicationrelationship_status'))
 * extended_status = Column(String(255))
 * driver_data = Column(String(255))
 
-State diagram for replication (status)::
+State diagram for replication (status)
+
+::
+
  <start>
                                           any error
  Create replica   +----------+             condition   +-------+

specs/juno/xio-iscsi-fc-volume-driver.rst

@@ -77,7 +77,8 @@ None
 Other end user impact
 ---------------------
 
-Addition of the X-IO volume driver will allow the end user to use X-IO storage as backend storage in Cinder.
+Addition of the X-IO volume driver will allow the end user to use X-IO storage
+as backend storage in Cinder.
 
 Performance Impact
 ------------------
@@ -95,7 +96,11 @@ The driver can be configured with the following parameters in cinder.conf:
 * ise_default_pool - storage pool to use for volume creation
 * iscsi_ip_address - IP to one ISCSI target interface on ISE
 
-The ISE ISCSI target interface specified in iscsi_ip_address will return all target portals available on that ISE, limited to the same subnet when receiving an ISCSI discover sendtargets request from a host identified as an Openstack host.  This was added to allow the host to use multipathing, if enabled on the hypervisor.
+The ISE ISCSI target interface specified in iscsi_ip_address will return all
+target portals available on that ISE, limited to the same subnet when receiving
+an ISCSI discover sendtargets request from a host identified as an Openstack
+host.  This was added to allow the host to use multipathing, if enabled on the
+hypervisor.
 
 Developer impact
 ----------------
@@ -156,7 +161,8 @@ Documentation Impact
 Support Matrix needs to be updated to include X-IO support.
 https://wiki.openstack.org/wiki/CinderSupportMatrix
 
-Block storage documentation needs to be updated to include X-IO volume driver information in the volume drivers section.
+Block storage documentation needs to be updated to include X-IO volume driver
+information in the volume drivers section.
 http://docs.openstack.org/
 
 References

specs/juno/xtremio_cinder_volume_driver.rst

@@ -15,10 +15,12 @@ This is to enable OpenStack to work on top of XtremIO storage.
 Problem description
 ===================
 
-This is a new Cinder driver that would enable Open Stack to work on top of XtremIO
+This is a new Cinder driver that would enable Open Stack to work on top of
-storage.
+XtremIO storage.
 The following diagram shows the command and data paths.
-``
+
+::
+
  +----------------+                 +--------+---------+
  |                |  Command        |                  |
  |                |  Path           |  Cinder +        |
@@ -44,21 +46,22 @@ The following diagram shows the command and data paths.
        |                                               |
        v                                               |
                                                        |
-+----------------+                                    |    +------------------+
+ +----------------+                                    |    +-----------------+
  |                |                                    |    |                 |
  |  Compute       |                                    |    |                 |
  |                |                                    +---->    XtremIO      |
  |                |           Data Link                     |    storeage     |
  |                +-----------------------------------------+                 |
-+----------------+                                         +------------------+
+ +----------------+                                         +-----------------+
-``
+
 
 Proposed change
 ===============
 
-2 new volume drivers for iSCSI and FC should be developed, bridging Open stack commands to
+2 new volume drivers for iSCSI and FC should be developed, bridging Open stack
-XtremIO managment system (XMS) using XMS Rest API.
+commands to XtremIO managment system (XMS) using XMS Rest API.
 The drivers should support the following Open stack actions:
+
  * Volume Create/Delete
  * Volume Attach/Detach
  * Snapshot Create/Delete

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 1.6
-envlist = py26,py27,py33,pypy,pep8
+envlist = docs,py27,pep8
 skipsdist = True
 
 [testenv]
@@ -9,9 +9,11 @@ install_command = pip install -U {opts} {packages}
 setenv =
    VIRTUAL_ENV={envdir}
 deps = -r{toxinidir}/requirements.txt
-       -r{toxinidir}/test-requirements.txt
 commands = python setup.py testr --slowest --testr-args='{posargs}'
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
 [testenv:pep8]
 commands = flake8