Docs: Eliminate warnings in docs generation

Fix all of the existing sphinx warnings, and treat warnings as errors in
future.

Change-Id: I084ef65da1002c47c7d05a68d6f0268b89a36a7a
Depends-On: https://review.openstack.org/553639
Depends-On: https://review.openstack.org/559348

doc/source/admin/auth-model.rst

@@ -77,7 +77,7 @@ which is consumed by *only* the trustee to obtain a
 such that the trustee has limited access to those
 roles delegated. In addition, the trustee has effective impersonation
 of the trustor user if it was selected when creating the trust.
-For more information, see :doc:`Identity management <identity-management>`.
+For more information, see `Identity Management trusts`_.
 
 Trusts authorization involves the following steps:
 
@@ -146,3 +146,5 @@ defined, then all the trustor roles are delegated to trustee.
 
    The trustor delegated roles must be pre-configured in the
    OpenStack Identity service before using them in the Orchestration service.
+
+.. _Identity management trusts: <https://docs.openstack.org/keystone/latest/admin/identity-use-trusts.html>

doc/source/admin/stack-domain-users.rst

@@ -125,8 +125,7 @@ The following steps are run during stack creation:
    in the stack domain are still assigned the ``heat_stack_user`` role, so
    the API surface they can access is limited through
    the :file:`policy.json` file.
-   For more  information, see :doc:`OpenStack Identity
-   documentation <identity-management>`.
+   For more  information, see `OpenStack Identity documentation`_.
 
 #. When API requests are processed, the Orchestration service performs
    an internal lookup, and allows stack details for a given stack to be
@@ -150,3 +149,5 @@ or::
 The stack owner uses the former (via ``openstack stack resource metadata
 STACK RESOURCE``), and any agents in the instance
 use the latter.
+
+.. _OpenStack Identity documentation: https://docs.openstack.org/keystone/latest/

doc/source/api/index.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
  Source Code Index
 ===================

doc/source/developing_guides/index.rst

@@ -11,17 +11,19 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+:orphan:
+
 Developing Guides
 =================
 
 .. toctree::
-       :maxdepth: 1
+    :maxdepth: 1
 
-    contributing/index
-    getting_started/on_devstack
-    developing_guides/architecture
-    developing_guides/pluginguide
-    developing_guides/schedulerhints
-    developing_guides/gmr
-    developing_guides/supportstatus
-    developing_guides/rally_on_gates
+    ../contributing/index
+    ../getting_started/on_devstack
+    architecture
+    pluginguide
+    schedulerhints
+    gmr
+    supportstatus
+    rally_on_gates

doc/source/developing_guides/pluginguide.rst

@@ -669,7 +669,7 @@ directories on the local file system where the engine will search for plug-ins.
 Simply place the file containing your resource in one of these directories and
 the engine will make them available next time the service starts.
 
-See :doc:`<../configuration/index>` for more information on configuring the
+See :doc:`../configuration/index` for more information on configuring the
 orchestration service.
 
 Testing

doc/source/developing_guides/rally_on_gates.rst

@@ -33,6 +33,7 @@ https://github.com/openstack/heat/blob/master/rally-scenarios/heat-fakevirt.yaml
 
 Obviously performance analysis make sense, when it can be compared with some
 another performance data. So two different approaches can be used for it:
+
  - Comparison of one part of code with some custom changes
    (see :ref:`check_performance_or_detect_regression`)
  - Comparison of two different code parts
@@ -116,6 +117,7 @@ that caching works correct.
 
 Also this approach may be used for detecting regressions. In this case workflow
 may be presented as follow list of steps:
+
  - add to task list (``heat-fakevirt.yaml``) existing or new tasks.
  - wait a result of this execution.
  - upload patchset with changes (new feature) and launch the same test again.

doc/source/ext/resources.py

@@ -391,6 +391,9 @@ def _filter_resources(prefix=None, path=None, statuses=None):
 
 
 def _load_all_resources():
+    from oslo_log import log as logging
+    logging.getLogger('heat.engine.environment').logger.setLevel(logging.ERROR)
+
     manager = plugin_manager.PluginManager('heat.engine.resources')
     resource_mapping = plugin_manager.PluginMapping('resource')
     res_plugin_mappings = resource_mapping.load_all(manager)

doc/source/getting_started/index.rst

@@ -11,6 +11,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+:orphan:
+
 Getting Started Guides
 ======================
 

doc/source/operating_guides/upgrades_guide.rst

@@ -37,7 +37,7 @@ Plan to upgrade
 Cold Upgrades
 =============
 
-Heat already supports "cold-upgrades" [1]_, where the heat services have to be
+Heat already supports "`cold-upgrades`_", where the heat services have to be
 down during the upgrade. For time-consuming upgrades, it may be unacceptable
 for the services to be unavailable for a long period of time. This type of
 upgrade is quite simple, follow the bellow steps:
@@ -66,7 +66,7 @@ A rolling upgrade would provide a better experience for the users and
 operators of the cloud. A rolling upgrade would allow individual heat-api and
 heat-engine services to be upgraded one at a time, with the rest of the
 services still available. This upgrade would have minimal downtime. Please
-check specs about rolling upgrades [2]_.
+check `spec about rolling upgrades`_.
 
 Prerequisites
 -------------
@@ -108,8 +108,8 @@ These following steps are the process to upgrade Heat with minimal downtime:
    for all upgrade services.
 
 5. Stop heat-engine gracefully, Heat has supported graceful shutdown features
-   [2]_. Then start new heat-engine with new code (and corresponding
-   configuration).
+   (see the `spec about rolling upgrades`_). Then start new heat-engine with
+   new code (and corresponding configuration).
 
    .. note::
 
@@ -143,16 +143,16 @@ These following steps are the process to upgrade Heat with minimal downtime:
       unprocessed and any IN_PROGRESS stacks would get stuck without any
       forward progress. The operator must be careful when shutting down the
       last engine, make sure queues have no unprocessed messages before
-      doing it. The operator can check the queues directly with RabbitMQ's
-      management plugin [3].
+      doing it. The operator can check the queues directly with `RabbitMQ`_'s
+      management plugin.
 
 8. Once all services are upgraded, double check the DB and services
 
 References
 ==========
 
-.. [1] https://governance.openstack.org/tc/reference/tags/assert_supports-upgrade.html
+.. _cold-upgrades: https://governance.openstack.org/tc/reference/tags/assert_supports-upgrade.html
 
-.. [2] https://review.openstack.org/#/c/407989/
+.. _spec about rolling upgrades: https://review.openstack.org/#/c/407989/
 
-.. [3] http://www.rabbitmq.com/management.html
+.. _RabbitMQ: http://www.rabbitmq.com/management.html

doc/source/template_guide/environment.rst

@@ -52,16 +52,14 @@ It also can contain some other sections:
     Merge strategies for merging parameters and parameter defaults from the
     environment file.
 
-Use the :option:`-e` option of the :command:`openstack stack create` command to
-create a stack using the environment defined in such a file.
+Use the `-e` option of the :command:`openstack stack create` command to create
+a stack using the environment defined in such a file.
 
 You can also provide environment parameters as a list of key/value pairs using
-the :option:`--parameter` option of the :command:`openstack stack create`
-command.
+the `--parameter` option of the :command:`openstack stack create` command.
 
 In the following example the environment is read from the :file:`my_env.yaml`
-file and an extra parameter is provided using the :option:`--parameter`
-option::
+file and an extra parameter is provided using the `--parameter` option::
 
    $ openstack stack create my_stack -e my_env.yaml --parameter "param1=val1;param2=val2" -t my_tmpl.yaml
 

heat/common/environment_util.py

@@ -152,7 +152,7 @@ def merge_environments(environment_files, files,
     :param files: mapping of stack filenames to contents
     :type  files: dict
     :param params: parameters describing the stack
-    :type  dict:
+    :type  params: dict
     :param param_schemata: parameter schema dict
     :type  param_schemata: dict
     """

heat/engine/environment.py

@@ -382,7 +382,7 @@ class ResourceRegistry(object):
 
         For a given resource we get the set of restricted actions.
 
-        Actions are set in this format via `resources`:
+        Actions are set in this format via `resources`::
 
             {
                 "restricted_actions": [update, replace]
@@ -410,7 +410,7 @@ class ResourceRegistry(object):
         For a given resource and a hook type, we check to see if the passed
         group of resources has the right hook associated with the name.
 
-        Hooks are set in this format via `resources`:
+        Hooks are set in this format via `resources`::
 
             {
                 "res_name": {

heat/engine/function.py

@@ -331,7 +331,7 @@ def dep_attrs(snippet, resource_name):
     appropriate.
 
     :returns: an iterator over the attributes of the specified resource that
-    are referenced in the template snippet.
+              are referenced in the template snippet.
     """
 
     if isinstance(snippet, Function):
@@ -354,7 +354,7 @@ def all_dep_attrs(snippet):
     appropriate.
 
     :returns: an iterator over the resource name, attribute name tuples of all
-    attributes that are referenced in the template snippet.
+              attributes that are referenced in the template snippet.
     """
 
     if isinstance(snippet, Function):

heat/engine/resource.py

@@ -1362,7 +1362,7 @@ class Resource(status.ResourceStatus):
         return False
 
     def needs_replace_failed(self):
-        """Needs replace if resource is in *_FAILED."""
+        """Needs replace if resource is in ``*_FAILED``."""
         return True
 
     def _needs_update(self, after, before, after_props, before_props,

heat/engine/resources/aws/cfn/wait_condition_handle.py

@@ -50,13 +50,14 @@ class WaitConditionHandle(wc_base.BaseWaitConditionHandle):
     def handle_signal(self, details=None):
         """Validate and update the resource metadata.
 
-        metadata must use the following format:
-        {
-            "Status" : "Status (must be SUCCESS or FAILURE)",
-            "UniqueId" : "Some ID, should be unique for Count>1",
-            "Data" : "Arbitrary Data",
-            "Reason" : "Reason String"
-        }
+        metadata must use the following format::
+
+            {
+                "Status" : "Status (must be SUCCESS or FAILURE)",
+                "UniqueId" : "Some ID, should be unique for Count>1",
+                "Data" : "Arbitrary Data",
+                "Reason" : "Reason String"
+            }
         """
         if details is None:
             return

heat/engine/resources/openstack/heat/software_deployment.py

@@ -51,7 +51,7 @@ class SoftwareDeployment(signal_responder.SignalResponder):
 
     Whenever this resource goes to an IN_PROGRESS state, it creates an
     ephemeral config that includes the inputs values plus a number of extra
-    inputs which have names prefixed with deploy_. The extra inputs relate
+    inputs which have names prefixed with ``deploy_``. The extra inputs relate
     to the current state of the stack, along with the information and
     credentials required to signal back the deployment results.
 

heat/engine/resources/openstack/heat/wait_condition_handle.py

@@ -195,12 +195,14 @@ class HeatWaitConditionHandle(wc_base.BaseWaitConditionHandle):
         """Validate and update the resource metadata.
 
         Metadata is not mandatory, but if passed it must use the following
-        format:
-        {
-            "status" : "Status (must be SUCCESS or FAILURE)",
-            "data" : "Arbitrary data",
-            "reason" : "Reason string"
-        }
+        format::
+
+            {
+                "status" : "Status (must be SUCCESS or FAILURE)",
+                "data" : "Arbitrary data",
+                "reason" : "Reason string"
+            }
+
         Optionally "id" may also be specified, but if missing the index
         of the signal received will be used.
         """

heat/engine/resources/openstack/keystone/role_assignments.py

@@ -22,30 +22,32 @@ from heat.engine import support
 class KeystoneRoleAssignmentMixin(object):
     """Implements role assignments between user/groups and project/domain.
 
-    heat_template_version: 2013-05-23
-
-    parameters:
-      ... Group or User parameters
-      group_role:
-        type: string
-        description: role
-      group_role_domain:
-        type: string
-        description: group role domain
-      group_role_project:
-        type: string
-        description: group role project
-
-    resources:
-      admin_group:
-        type: OS::Keystone::Group OR OS::Keystone::User
-        properties:
-          ... Group or User properties
-          roles:
-            - role: {get_param: group_role}
-              domain: {get_param: group_role_domain}
-            - role: {get_param: group_role}
-              project: {get_param: group_role_project}
+    For example::
+
+        heat_template_version: 2013-05-23
+
+        parameters:
+          ... Group or User parameters
+          group_role:
+            type: string
+            description: role
+          group_role_domain:
+            type: string
+            description: group role domain
+          group_role_project:
+            type: string
+            description: group role project
+
+        resources:
+          admin_group:
+            type: OS::Keystone::Group OR OS::Keystone::User
+            properties:
+              ... Group or User properties
+              roles:
+                - role: {get_param: group_role}
+                  domain: {get_param: group_role_domain}
+                - role: {get_param: group_role}
+                  project: {get_param: group_role_project}
     """
 
     PROPERTIES = (

heat/engine/resources/openstack/neutron/quota.py

@@ -25,6 +25,7 @@ class NeutronQuota(neutron.NeutronResource):
 
     Neutron Quota is used to manage operational limits for projects. Currently,
     this resource can manage Neutron's quotas for:
+
         - subnet
         - network
         - floatingip

heat/engine/resources/openstack/nova/quota.py

@@ -25,6 +25,7 @@ class NovaQuota(resource.Resource):
 
     Nova Quota is used to manage operational limits for projects. Currently,
     this resource can manage Nova's quotas for:
+
         - cores
         - fixed_ips
         - floating_ips

heat/engine/service.py

@@ -1185,11 +1185,11 @@ class EngineService(service.ServiceBase):
         :param params: Stack Input Params
         :param files: Files referenced from the template
         :param environment_files: optional ordered list of environment file
-               names included in the files dict
+                                  names included in the files dict
         :type  environment_files: list or None
         :param show_nested: if True, any nested templates will be checked
         :param ignorable_errors: List of error_code to be ignored as part of
-        validation
+                                 validation
         """
         LOG.info('validate_template')
         if template is None:

heat/engine/stack.py

@@ -616,6 +616,7 @@ class Stack(collections.Mapping):
         error if this option is lost.
 
         Note:
+
         - This doesn't return the args(name, template) but only the kwargs.
         - We often want to start 'fresh' so don't want to maintain the old
           status, action and status_reason.
@@ -1126,13 +1127,14 @@ class Stack(collections.Mapping):
 
         :param action: action that should be executed with stack resources
         :param reverse: define if action on the resources need to be executed
-         in reverse order (resources - first and then res dependencies )
+                        in reverse dependency order
         :param post_func: function that need to be executed after
-        action complete on the stack
+                          action complete on the stack
         :param aggregate_exceptions: define if exceptions should be aggregated
         :param pre_completion_func: function that need to be executed right
-        before action completion. Uses stack ,action, status and reason as
-        input parameters
+                                    before action completion; uses stack,
+                                    action, status and reason as input
+                                    parameters
         """
         try:
             lifecycle_plugin_utils.do_pre_ops(self.context, self,
@@ -2079,12 +2081,12 @@ class Stack(collections.Mapping):
 
         1. Delete the resources from DB.
         2. If the stack failed, update the current_traversal to empty string
-        so that the resource workers bail out.
+           so that the resource workers bail out.
         3. Delete previous raw template if stack completes successfully.
         4. Deletes all sync points. They are no longer needed after stack
            has completed/failed.
         5. Delete the stack if the action is DELETE.
-       """
+        """
         resource_objects.Resource.purge_deleted(self.context, self.id)
 
         exp_trvsl = self.current_traversal

heat/engine/template.py

@@ -337,9 +337,9 @@ class Template(collections.Mapping):
         not provided, a new empty HOT template of version "2015-04-30"
         is returned.
 
-        :param version: A tuple containing version header of the
-        template: version key and value. E.g. ("heat_template_version",
-        "2015-04-30")
+        :param version: A tuple containing version header of the template
+                        version key and value,
+                        e.g. ``('heat_template_version', '2015-04-30')``
         :returns: A new empty template.
         """
         if from_template:

heat/rpc/client.py

@@ -217,7 +217,7 @@ class EngineClient(object):
 
         :param ctxt: RPC context.
         :param stack_identity: Name of the stack you want to show, or None to
-        show all
+                               show all
         :param resolve_outputs: If True, stack outputs will be resolved
         """
         return self.call(ctxt, self.make_msg('show_stack',
@@ -381,10 +381,10 @@ class EngineClient(object):
         :param params: Stack Input Params/Environment
         :param files: files referenced from the environment/template.
         :param environment_files: ordered list of environment file names
-               included in the files dict
+                                  included in the files dict
         :param show_nested: if True nested templates will be validated
         :param ignorable_errors: List of error_code to be ignored as part of
-        validation
+                                 validation
         """
         return self.call(ctxt, self.make_msg(
             'validate_template',
@@ -498,11 +498,11 @@ class EngineClient(object):
 
     def list_template_functions(self, ctxt, template_version,
                                 with_condition=False):
-        """Get a list of available functions in a given template.
+        """Get a list of available functions in a given template type.
 
         :param ctxt: RPC context
-        :param template_name : name of the template which function list you
-                               want to get
+        :param template_version: template format/version tuple for which you
+                                 want to get the list of functions.
         :param with_condition: return includes condition functions.
         """
         return self.call(ctxt,

setup.cfg

@@ -206,6 +206,3 @@ input_file = heat/locale/heat.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = heat/locale/heat.pot
-
-[build_sphinx]
-warning-is-error = False

tox.ini

@@ -64,7 +64,7 @@ commands =
 deps = -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf doc/build
-  sphinx-build -b html doc/source doc/build/html
+  sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:api-ref]
 # This environment is called from CI scripts to test and publish