Merge "Docs: Eliminate warnings in docs generation"

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
+   For more  information, see `OpenStack Identity documentation`_.
-   documentation <identity-management>`.
 
 #. 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
 
-    contributing/index
+    ../contributing/index
-    getting_started/on_devstack
+    ../getting_started/on_devstack
-    developing_guides/architecture
+    architecture
-    developing_guides/pluginguide
+    pluginguide
-    developing_guides/schedulerhints
+    schedulerhints
-    developing_guides/gmr
+    gmr
-    developing_guides/supportstatus
+    supportstatus
-    developing_guides/rally_on_gates
+    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
+   (see the `spec about rolling upgrades`_). Then start new heat-engine with
-   configuration).
+   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
+      doing it. The operator can check the queues directly with `RabbitMQ`_'s
-      management plugin [3].
+      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
+Use the `-e` option of the :command:`openstack stack create` command to create
-create a stack using the environment defined in such a file.
+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`
+the `--parameter` option of the :command:`openstack stack create` command.
-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`
+file and an extra parameter is provided using the `--parameter` option::
-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/resource.py

@@ -1380,7 +1380,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,7 +50,8 @@ class WaitConditionHandle(wc_base.BaseWaitConditionHandle):
     def handle_signal(self, details=None):
         """Validate and update the resource metadata.
 
-        metadata must use the following format:
+        metadata must use the following format::
+
             {
                 "Status" : "Status (must be SUCCESS or FAILURE)",
                 "UniqueId" : "Some ID, should be unique for Count>1",

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:
+        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,6 +22,8 @@ from heat.engine import support
 class KeystoneRoleAssignmentMixin(object):
     """Implements role assignments between user/groups and project/domain.
 
+    For example::
+
         heat_template_version: 2013-05-23
 
         parameters:

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/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.
@@ -1127,13 +1128,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
         :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
+                                    before action completion; uses stack,
-        input parameters
+                                    action, status and reason as input
+                                    parameters
         """
         try:
             lifecycle_plugin_utils.do_pre_ops(self.context, self,

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
+        :param version: A tuple containing version header of the template
-        template: version key and value. E.g. ("heat_template_version",
+                        version key and value,
-        "2015-04-30")
+                        e.g. ``('heat_template_version', '2015-04-30')``
         :returns: A new empty template.
         """
         if from_template:

heat/rpc/client.py

@@ -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
+        :param template_version: template format/version tuple for which you
-                               want to get
+                                 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

@@ -68,7 +68,7 @@ basepython = python3
 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]
 basepython = python3