Fix specification warnings

This patch set fixes all specification warnings and
set warning-is-error flag to True.

Change-Id: I9a6132cfd0d010db21c148be53b6bb5523eb6f5c

doc/source/conf.py

@@ -32,6 +32,7 @@ extensions = ['redirect',
               'sphinx.ext.autodoc',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode',
+              'sphinx.ext.mathjax',
               'oslosphinx',
               'yasfb',
              ]

requirements.txt

@@ -1,7 +1,7 @@
 oslosphinx
-pbr>=0.6,<1.0
+pbr>=2.0.0,!=2.1.0 # Apache-2.0
-sphinx>=1.1.2,<1.2
+sphinx>=1.6.2 # BSD
 testrepository>=0.0.18
-testtools>=0.9.34
+testtools>=1.4.0
 yasfb>=0.5.1
 doc8 # Apache-2.0

setup.cfg

@@ -15,6 +15,7 @@ classifier =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+warning-is-error = 1
 
 [pbr]
 warnerrors = False

specs/newton/implemented/sd-strategy.rst

@@ -89,13 +89,13 @@ probable difference in the number of node vcpus. Therefore we transform
 VM CPU utilization to overall host CPU utilization. The following pseudocode
 shows the right way of transforming:
 
-:math:`cpu_impact = cpu_util * vm_vcpus/host_vcpus`
+:math:`cpu_{impact} = cpu_{util} * {vm_vcpus}/{host_vcpus}`
 
 After that the load values of nodes are normalised and the new
 standard deviation is calculated with them.
 The total standard deviation is calculated as weighted arithmetic mean:
 
-:math:`\sum weight_metric*sd_metric`, where:
+:math:`\sum weight_{metric}*sd_{metric}`, where:
 
 * weight_metric is the weight of metric. The value of weight is to be in
   range(0, 1). Each weight of metric is set by `watcher input parameters`_.

specs/ocata/implemented/watcher-notifications-ovo.rst

@@ -70,7 +70,7 @@ number that will facilitate retro-compatibility whenever adding new fields.
 The basic structure for all notifications will be the same as the one that is
 used in Nova for the `versioned-notification-api blueprint`_, i.e.:
 
-.. code-block:: json
+.. code-block:: none
 
     {
         "priority": "INFO",

specs/pike/approved/build-baremetal-data-model.rst

@@ -113,6 +113,7 @@ ironic node-create -d your_driver agent_ipmitool \
                    -i ipmi_password=<ipmi_password> \
                    -e compute_node=compute.node.id \
                    -u ironic_node_uuid
+
 compute.node.id is the compute node ID saved in CCDM
 (Compute Cluster Data Model)
 
@@ -120,6 +121,7 @@ compute.node.id is the compute node ID saved in CCDM
 2) On watcher, build the Baremetal Cluster Data Model (BCDM) by
 periodically requesting Ironic service.
 The Baremetal Cluster Data Model structure is shown as followings
+
 {
   "uuid": "4f37180e-c310-4327-a286-d5ab9ffc6497",
   "power_state": "power on",

specs/pike/approved/workload-characterization-grammar.rst

@@ -129,7 +129,7 @@ Example :
 **Parse and validate workload grammar**
 
 
-Use `TOSCA-Parser_  module to parse a TOSCA serialized workload
+Use `TOSCA-Parser`_  module to parse a TOSCA serialized workload
 grammar and validate it by applying values from telemetry
 or other metrics.
 

specs/pike/implemented/add-power-on-and-off-in-watcher.rst

@@ -17,6 +17,7 @@ without VMs. And when the workload increases watcher will trigger a "power on"
 request to fullfill the service requirements.
 
 This feature includes four sub-features:
+
 * Build a new baremetal data model in Watcher.
 * Add new actions "power on" and "power off" in Watcher.
 * Implement a new strategy based on 'baremetal' and 'compute' data models,

specs/pike/implemented/audit-tag-vm-metadata.rst

@@ -43,7 +43,7 @@ the Audit Scope to exclude VMs by metadata.
 
 Example -
 
-.. code-block:: json
+.. code-block:: none
 
      "scope": [
           {"host_aggregates": [
@@ -135,7 +135,7 @@ Work Items
 ----------
 * Platform owners or automations external to watcher will set the VM Metadata
 
-.. code-block:: json
+.. code-block:: none
 
     # nova meta vm_name set optimize=True
 
@@ -196,6 +196,5 @@ History
 N/A
 
 .. _Audit: http://docs.openstack.org/developer/watcher/glossary.html#audit
-.. _Strategy:
+.. _Strategy: http://docs.openstack.org/developer/watcher/glossary.html#strategies
-http://docs.openstack.org/developer/watcher/glossary.html#strategies
 .. _Audit Scope: https://specs.openstack.org/openstack/watcher-specs/specs/newton/approved/define-the-audit-scope.html

specs/pike/implemented/cancel-action-plan.rst

@@ -127,6 +127,9 @@ Work Items
   method for all the tasks(actions) added in the flow. In the revert method of
   action, current action state is checked and based on the action state
   (PENDING, ONGOING, SUCCEEDED) revert method will execute defined steps.
+
+  .. code-block:: python
+
       e.g. if action_state is PENDING:
             # update action_state to CANCELLED
            if action_state is ONGOING:

specs/pike/implemented/dynamic-action-description.rst

@@ -126,6 +126,7 @@ Alternatives
       "event_type": "action_info.emit",
       "message_id": "cbcf9f2c-7c53-4b4d-91ec-db49cca024b6"
     }
+
 The implementation is as follows:
 https://review.openstack.org/#/c/454638/
 But in my test, The number of received notifications is often less than

specs/pike/implemented/jsonschema-validation.rst

@@ -104,6 +104,7 @@ Work Items
 ----------
 
 * Remove voluptuous schemas
+
 As of now, voluptuous is used to:
 - validate the input parameters of a Watcher action when it gets to the
 Applier.