Fix tox errors and warnings in the devref

Formatting errors have crept into the manila devref
and have been accumulating over time. It would
be nice to fix these as part of the devref cleanup.

Closes-Bug: #1583850
Partially-implements: bp improve-manila-developer-docs
Change-Id: I7ec954e720b4b88a21e265cd71ea598ea9a5213b

doc/source/adminref/quick_start.rst

@@ -170,7 +170,7 @@ Result::
     +-------------+----------------------------------+
 
 
-4) Create the Share Filesystems service API endpoints::
+4) Create the Share Filesystems service API endpoints:
 
 .. code-block:: console
 

doc/source/devref/ganesha.rst

@@ -185,7 +185,7 @@ Known Restrictions
 - The library does not support network segmented multi-tenancy model but
   instead works over a flat network, where the tenants share a network.
 
-.. _ganesha_known_issues
+.. _ganesha_known_issues:
 
 Known Issues
 ------------

doc/source/devref/hpe_3par_driver.rst

@@ -14,7 +14,7 @@
       under the License.
 
 HPE 3PAR Driver
-==============
+===============
 
 The HPE 3PAR manila driver provides NFS and CIFS shared file systems to
 OpenStack using HPE 3PAR's File Persona capabilities.
@@ -69,7 +69,7 @@ On the HPE 3PAR array:
 - The array class and hardware configuration must support File Persona
 
 Pre-Configuration on the HPE 3PAR
---------------------------------
+---------------------------------
 
 - HPE 3PAR File Persona must be initialized and started (:code:`startfs`)
 - A File Provisioning Group (FPG) must be created for use with manila
@@ -232,7 +232,7 @@ the original functionality is honored and the file tree remains untouched.
 be specified to create further customization.
 
 The :mod:`manila.share.drivers.hpe.hpe_3par_driver` Module
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: manila.share.drivers.hpe.hpe_3par_driver
     :noindex:

doc/source/devref/scheduler.rst

@@ -49,10 +49,10 @@ The :mod:`manila.scheduler.host_manager` Module
     :show-inheritance:
 
 
-The :mod:`manila.scheduler.rcpapi` Module
+The :mod:`manila.scheduler.rpcapi` Module
 -----------------------------------------
 
-.. automodule:: manila.scheduler.rcpapi
+.. automodule:: manila.scheduler.rpcapi
     :noindex:
     :members:
     :undoc-members:

manila/scheduler/filters/share_replication.py

@@ -27,6 +27,7 @@ class ShareReplicationFilter(base_host.BaseHostFilter):
         """Return True if 'active' replica's host can replicate with host.
 
         Design of this filter:
+
             - Share replication is symmetric. All backends that can
               replicate between each other must share the same
               'replication_domain'.
@@ -34,6 +35,7 @@ class ShareReplicationFilter(base_host.BaseHostFilter):
               this filter checks for 'replication_domain' capability.
             - For scheduling a replica, it checks for the
               'replication_domain' compatibility.
+
         """
         active_replica_host = filter_properties.get('request_spec', {}).get(
             'active_replica_host')

manila/scheduler/host_manager.py

@@ -149,7 +149,7 @@ class HostState(object):
         """Update information about a host from its share_node info.
 
         'capability' is the status info reported by share backend, a typical
-        capability looks like this:
+        capability looks like this::
 
             capability = {
                 'share_backend_name': 'Local NFS',    #\
@@ -162,20 +162,23 @@ class HostState(object):
                 'fancy_capability_1': 'eat',          #  stats & capabilities
                 'fancy_capability_2': 'drink',        #/
 
-            'pools': [
+                'pools':[
-                {'pool_name': '1st pool',         #\
+                  {
-                 'total_capacity_gb': 500,        #  mandatory stats for
+                     'pool_name': '1st pool',         #\
-                 'free_capacity_gb': 230,         #  pools
+                     'total_capacity_gb': 500,        #  mandatory stats
+                     'free_capacity_gb': 230,         #   for pools
                      'allocated_capacity_gb': 270,    # |
                      'qos': 'False',                  # |
                      'reserved_percentage': 0,        #/
 
                      'dying_disks': 100,              #\
                      'super_hero_1': 'spider-man',    #  optional custom
-                 'super_hero_2': 'flash',         #  stats & capabilities
+                     'super_hero_2': 'flash',         #  stats &
-                 'super_hero_3': 'neoncat'        #/
+                     'super_hero_3': 'neoncat',       #  capabilities
+                     'super_hero_4': 'green lantern', #/
                    },
-                {'pool_name': '2nd pool',
+                  {
+                     'pool_name': '2nd pool',
                      'total_capacity_gb': 1024,
                      'free_capacity_gb': 1024,
                      'allocated_capacity_gb': 0,
@@ -184,10 +187,8 @@ class HostState(object):
 
                      'dying_disks': 200,
                      'super_hero_1': 'superman',
-                 'super_hero_2': ' ',
                      'super_hero_2': 'Hulk',
-                 }
+                  }]
-            ]
             }
         """
         self.update_capabilities(capability, service)

manila/scheduler/rpcapi.py

@@ -32,8 +32,8 @@ class SchedulerAPI(object):
 
         1.0 - Initial version.
         1.1 - Add get_pools method
-        1.2 - Introduce Share Instances:
+        1.2 - Introduce Share Instances. Replace ``create_share()`` with
-            Replace create_share() - > create_share_instance()
+        ``create_share_instance()``
         1.3 - Add create_consistency_group method
         1.4 - Add migrate_share_to_host method
         1.5 - Add create_share_replica

manila/share/driver.py

@@ -680,12 +680,25 @@ class ShareDriver(object):
         the failure.
 
         :param snapshot: ShareSnapshotInstance model with ShareSnapshot data.
-                         Example:
+
-                         {'id': <instance id>, 'snapshot_id': < snapshot id>,
+        Example::
-                          'provider_location': <location>, ......}
+            {
+            'id': <instance id>,
+            'snapshot_id': < snapshot id>,
+            'provider_location': <location>,
+            ...
+            }
+
         :param driver_options: Optional driver-specific options provided
-                               by admin. Example:
+            by admin.
-                               {'key': 'value', ......}
+
+        Example::
+
+            {
+            'key': 'value',
+            ...
+            }
+
         :return: model_update dictionary with required key 'size',
             which should contain size of the share snapshot.
         """

manila/share/drivers/hitachi/hds_hnas.py

@@ -242,7 +242,7 @@ class HDSHNASDriver(driver.ShareDriver):
 
         :param context: The `context.RequestContext` object for the request
         :param snapshot: Snapshot that will be deleted.
-        :param share_server:Data structure with share server information.
+        :param share_server: Data structure with share server information.
             Not used by this driver.
         """
         share_id = self._get_hnas_share_id(snapshot['share_id'])

manila/share/drivers/huawei/huawei_nas.py

@@ -43,7 +43,7 @@ class HuaweiNasDriver(driver.ShareDriver):
     """Huawei Share Driver.
 
     Executes commands relating to Shares.
-    API version history:
+    API version history::
 
         1.0 - Initial version.
         1.1 - Add shrink share.