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
This commit is contained in:
Zane Bitter 2018-03-15 14:30:28 -04:00
parent a4a6a00809
commit 76ec5af884
26 changed files with 109 additions and 91 deletions

View File

@ -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>

View File

@ -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/

View File

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

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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)

View File

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

View File

@ -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

View File

@ -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

View File

@ -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
"""

View File

@ -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": {

View File

@ -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):

View File

@ -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,

View File

@ -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

View File

@ -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.

View File

@ -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.
"""

View File

@ -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
For example::
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
heat_template_version: 2013-05-23
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}
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 = (

View File

@ -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

View File

@ -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

View File

@ -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:

View File

@ -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

View File

@ -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:

View File

@ -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,

View File

@ -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

View File

@ -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