From 41be2394627fcc44f9403112636c5c703caa9eb2 Mon Sep 17 00:00:00 2001 From: Tin Lam Date: Sat, 26 Mar 2016 02:31:02 -0500 Subject: [PATCH] Removed warnings from building docs Removed all warnings from running 'tox -e docs'. Setting warnerrors = true in setup.cfg. Change-Id: I00438f6a505d696fa5d1261a4f016118bdd4faf1 Closes-Bug: #1561985 --- doc/source/articles/telnet_example.rst | 59 +++++++++++++++++++ doc/source/articles/workflow.rst | 10 ++-- doc/source/draft/admin-guide/policy_enf.rst | 1 - .../appdev-guide/hotpackages/compose.rst | 6 +- .../draft/appdev-guide/murano_pl/actions.rst | 6 +- .../draft/appdev-guide/murano_pl/core_lib.rst | 15 +++++ .../muranopackages/package_structure.rst | 2 +- doc/source/draft/index.rst | 2 +- doc/source/index.rst | 2 +- doc/source/specification/murano-env-temp.rst | 4 +- setup.cfg | 5 ++ 11 files changed, 95 insertions(+), 17 deletions(-) create mode 100644 doc/source/articles/telnet_example.rst diff --git a/doc/source/articles/telnet_example.rst b/doc/source/articles/telnet_example.rst new file mode 100644 index 00000000..d08b1a4f --- /dev/null +++ b/doc/source/articles/telnet_example.rst @@ -0,0 +1,59 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http//www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. +.. +.. _telnet-example: + +Telnet Example +-------------- + +.. code-block:: yaml + + Namespaces: + =: io.murano.apps.linux + std: io.murano + res: io.murano.resources + + + Name: Telnet + + # Inheritance from io.murano.Application class + # (located at Murano Core library) indicates, + # that this is a complete application + # and that 'deploy' method has to be defined. + Extends: std:Application + + Properties: + name: + Contract: $.string().notNull() + + instance: + Contract: $.class(res:Instance).notNull() + + + Methods: + deploy: + Body: + # Determine the environment to which the application belongs. + # This message will be stored in deployment logs and available in UI + - $this.find(std:Environment).reporter.report($this, 'Creating VM for Telnet instace.') + # Deploy VM + - $.instance.deploy() + - $this.find(std:Environment).reporter.report($this, 'Instance is created. Setup Telnet service.') + # Create instance of murano resource class. Agent will use it to find + # corresponding execution plan by the file name + - $resources: new('io.murano.system.Resources') + # Deploy Telnet + - $template: $resources.yaml('DeployTelnet.template') + # Send prepared execution plan to Murano agent + - $.instance.agent.call($template, $resources) + - $this.find(std:Environment).reporter.report($this, 'Telnet service setup is done.') diff --git a/doc/source/articles/workflow.rst b/doc/source/articles/workflow.rst index 62641f24..010d7cb8 100644 --- a/doc/source/articles/workflow.rst +++ b/doc/source/articles/workflow.rst @@ -42,14 +42,14 @@ parameters the user selected prior to deployment. Examples are: Each object in this *model* has an ID so that the state of each can be tracked. The classes that are required are determined by the application's manifest. In -the :ref:`Telnet example ` only one class is explicitly +the :ref:`Telnet example ` only one class is explicitly required; the telnet application definition. -The :ref:`Telnet class definition ` refers to several other +The :ref:`Telnet class definition ` refers to several other classes. It extends :ref:`Application` and it requires an :ref:`Instance`. It also refers to the :ref:`Environment` in which it will be contained, -sends reports through the environment's :ref:`io.murano.system.StatusReporter` -and adds security group rules to the :ref:`SecurityGroupManager`. +sends reports through the environment's :ref:`status-reporter` +and adds security group rules to the :ref:`security-group-manager`. Step 2. Load definitions @@ -75,7 +75,7 @@ to murano-agent (see later). The next stage is to deploy each application the environment knows about in turn, by running deploy() for each application. This happens concurrently for all the applications belonging to an instance. -In the :ref:`Telnet example ` (under *Workflow*), the workflow +In the :ref:`Telnet example ` (under *Workflow*), the workflow dictates sending a status message (via the environment's *reporter*, and configuring some security group rules. It is at this stage that the engine first contacts Heat to request information about any pre-existing resources diff --git a/doc/source/draft/admin-guide/policy_enf.rst b/doc/source/draft/admin-guide/policy_enf.rst index e184ff32..6b5dcda3 100644 --- a/doc/source/draft/admin-guide/policy_enf.rst +++ b/doc/source/draft/admin-guide/policy_enf.rst @@ -40,7 +40,6 @@ the deployment fails as well. .. _Congress: https://wiki.openstack.org/wiki/Congress -.. include:: /draft/admin-guide/policy_enforcement/policy_enf_overview.rst .. include:: /draft/admin-guide/policy_enforcement/policy_enf_setup.rst .. include:: /draft/admin-guide/policy_enforcement/policy_enf_rules.rst .. include:: /draft/admin-guide/policy_enforcement/policy_enf_dev.rst diff --git a/doc/source/draft/appdev-guide/hotpackages/compose.rst b/doc/source/draft/appdev-guide/hotpackages/compose.rst index 43bae678..7a24cd27 100644 --- a/doc/source/draft/appdev-guide/hotpackages/compose.rst +++ b/doc/source/draft/appdev-guide/hotpackages/compose.rst @@ -15,7 +15,7 @@ Just choose the desired Heat Orchestration Template and perform the following co :: -murano package-create --template wordpress/template.yaml + murano package-create --template wordpress/template.yaml Note, that optional parameters could be specified: @@ -77,10 +77,10 @@ Application package could be composed manually. Follow the 5 steps below. `Applications` page looks like: -.. image:: chef_server.png +.. image:: /draft/appdev-guide/hotpackages/chef_server.png The configuration form, where you can enter template parameters, will be generated automatically and looks as follows: -.. image:: chef_server_form.png +.. image:: /draft/appdev-guide/hotpackages/chef_server_form.png After filling the form the application is ready to be deployed. diff --git a/doc/source/draft/appdev-guide/murano_pl/actions.rst b/doc/source/draft/appdev-guide/murano_pl/actions.rst index f6728f2d..3b03b1f5 100644 --- a/doc/source/draft/appdev-guide/murano_pl/actions.rst +++ b/doc/source/draft/appdev-guide/murano_pl/actions.rst @@ -1,8 +1,8 @@ -.. _actions: - .. toctree:: :maxdepth: 2 +.. _actions: + ============== Murano actions ============== @@ -74,4 +74,4 @@ Response: } } } - } \ No newline at end of file + } diff --git a/doc/source/draft/appdev-guide/murano_pl/core_lib.rst b/doc/source/draft/appdev-guide/murano_pl/core_lib.rst index 3945c2cc..6851c60d 100644 --- a/doc/source/draft/appdev-guide/murano_pl/core_lib.rst +++ b/doc/source/draft/appdev-guide/murano_pl/core_lib.rst @@ -27,6 +27,7 @@ Classes included in the Murano core library are as follows: **io.murano.system** - :ref:`logger` +- :ref:`status-reporter` .. _object: @@ -321,3 +322,17 @@ This method uses the ERROR level: * `OpenStack networking logging configuration `_. + +.. _status-reporter: + +Class: StatusReporter +--------------------- + +Provides feedback feature. To follow the deployment process in the UI, all status changes should be included +in the application configuration. + +.. seealso:: + + Source `StatusReporter.yaml + `_ + file. diff --git a/doc/source/draft/appdev-guide/muranopackages/package_structure.rst b/doc/source/draft/appdev-guide/muranopackages/package_structure.rst index 1521b0c3..8c5c4ee1 100644 --- a/doc/source/draft/appdev-guide/muranopackages/package_structure.rst +++ b/doc/source/draft/appdev-guide/muranopackages/package_structure.rst @@ -38,4 +38,4 @@ The application package root folder should contain the following: Here is the visual representation of the Murano application package structure: -.. image:: muranopackages/structure.png +.. image:: /draft/appdev-guide/muranopackages/structure.png diff --git a/doc/source/draft/index.rst b/doc/source/draft/index.rst index 72ba7c35..05b8bb9d 100644 --- a/doc/source/draft/index.rst +++ b/doc/source/draft/index.rst @@ -102,7 +102,7 @@ Contributing contributor-guide/how_to_contribute contributor-guide/dev_guidelines contributor-guide/plugins - contributor-guide/deploy_local_dev_env + contributor-guide/dev_env contributor-guide/testing contributor-guide/doc_guidelines diff --git a/doc/source/index.rst b/doc/source/index.rst index 4379a9b1..5c03fa72 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -83,7 +83,7 @@ Using Murano draft/enduser-guide/quickstart draft/enduser-guide/manage_environments draft/enduser-guide/manage_applications - draft/enduser-guide/log_into_murano_instance + draft/enduser-guide/log_in_to_murano_instance draft/enduser-guide/deploying_using_cli diff --git a/doc/source/specification/murano-env-temp.rst b/doc/source/specification/murano-env-temp.rst index 26c39ee8..4c46b01a 100644 --- a/doc/source/specification/murano-env-temp.rst +++ b/doc/source/specification/murano-env-temp.rst @@ -342,7 +342,7 @@ Get applications information from an environment template +----------+-------------------------------------+-----------------------------------+ | Method | URI | Description | -+==========+====================================+====================================+ ++==========+=====================================+===================================+ | GET | /templates/{env-temp-id}/services | It obtains the service description| +----------+-------------------------------------+-----------------------------------+ @@ -408,7 +408,7 @@ Create an environment from an environment template +----------+--------------------------------------------+--------------------------------------+ | Method | URI | Description | -+==========+================================+==================================================+ ++==========+============================================+======================================+ | POST | /templates/{env-temp-id}/create-environment| Create an environment | +----------+--------------------------------------------+--------------------------------------+ diff --git a/setup.cfg b/setup.cfg index 84548cd0..ab908f03 100644 --- a/setup.cfg +++ b/setup.cfg @@ -86,3 +86,8 @@ input_file = murano/locale/murano.pot keywords = _ gettext ngettext l_ lazy_gettext mapping_file = babel.cfg output_file = murano/locale/murano.pot + +[pbr] +# Treat sphinx warnings as errors during the docs build; this helps us keep +# the documentation clean. +warnerrors = true