openstack/deb-murano
Code Issues Proposed changes

Mark doc warnings as errors

Browse Source 
This commit sets warning-is-error for sphinx_build in setup.cfg and also
fixes multiple warnings to make the build pass

* Removed :option: see https://docs.openstack.org/contributor-guide/rst-conv/inline-markups.html#option
* Removed stale and unreferenced documents
* Marked telnet_example as orphan
* Added first-app to the index
* multiple code-block fixes

Change-Id: I9c659860fcb4f29fba5f7f07a6a952becfc354da
This commit is contained in:
Kirill Zaitsev 2017-07-07 12:49:04 +03:00
parent df8002303f
commit aafd1f0a9d
20 changed files with 70 additions and 332 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/administrator-guide/admin_troubleshooting.rst
View File

@ -48,7 +48,7 @@ If any issues occur, first of all verify the following:
**Failed to execute `murano-db-manage`**
* Make sure the :option:`--config-file` option is provided.
* Make sure the ``--config-file`` option is provided.
* Check `connection` parameter in the provided configuration file. It should
be a `connection string <http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html>`_.
@ -112,7 +112,7 @@ Workarounds:
In murano, the corresponding configuration option is located in the
``engine`` section:
.. code-block:: console
.. code-block:: ini
[engine]
@ -175,4 +175,4 @@ There are no messages provided in applications themselves:
2015-09-21 11:16:43 — Deployment finished successfully
To fix the issue, set the ``driver`` option in the :file:`murano.config` file
to ``messagingv2``.
to ``messagingv2``.

6
doc/source/administrator-guide/configure_cloud_foundry_service_broker.rst
View File

@ -116,7 +116,7 @@ Devstack installation
~~~~~~~~~~~~~~~~~~~~~
It is really easy to enable service broker in your devstack installation.
You need simply update your :file:`local.conf` with the following:
You need simply update your ``local.conf`` with the following:
.. code-block:: ini
@ -162,7 +162,7 @@ To access and use murano packages through Cloud Foundry, you need to perform fol
.. note::
You can use :command:`service-access` command to see human-readable list of packages.
You can use ``service-access`` command to see human-readable list of packages.
#. Provision murano service through Cloud Foundry.
@ -180,7 +180,7 @@ To access and use murano packages through Cloud Foundry, you need to perform fol
},
"keyname": "nstarodubtsev",
"assignFloatingIp": "True",
"name": <name_pattern>,
"name": "<name_pattern>",
"availabilityZone": "nova",
"image": "1b9ff37e-dff3-4308-be08-9185705dad91"
},

14
doc/source/administrator-guide/prepare_lab.rst
View File

@ -121,20 +121,20 @@ Steps to reproduce test:
#. Ensure that there is NO KVM PROCESSES on the host. To do this, run
command:
::
.. code-block:: console
ps aux | grep kvm
#. Make 5 copies of Windows image file:
::
.. code-block:: console
for i in $(seq 5); do \
cp ws-2012-std.qcow2 ws-2012-std-$i.qcow2; done
#. Create script start-vm.sh in the folder with .qcow2 files:
::
.. code-block:: console
#!/bin/bash
[ -z $1 ] || echo "VM count not provided!"; exit 1
@ -147,13 +147,13 @@ Steps to reproduce test:
appears. To view VM’s desktop, connect with VNC viewer to your host
to VNC screen :1 (port 5901):
::
.. code-block:: console
sudo ./start-vm.sh 1
#. Turn VM off. You may simply kill all KVM processes by
::
.. code-block:: console
sudo killall kvm
@ -162,13 +162,13 @@ Steps to reproduce test:
window appears. To view VM’s desktops, connect with VNC viewer to your
host to VNC screens :1 thru :5 (ports 5901-5905):
::
.. code-block:: console
sudo ./start-vm.sh 5
#. Turn VMs off. You may simply kill all KVM processes by
::
.. code-block:: console
sudo killall kvm

8
doc/source/administrator-guide/using_glare.rst
View File

@ -67,12 +67,12 @@ DevStack installation
to view the empty list of packages.
Alternatively, use the :command:`murano` command.
#. Use :option:`--murano-packages-service` option to specify backend,
#. Use ``--murano-packages-service`` option to specify backend,
used by :command:`murano` command. Set it to ``glare`` for using ``Glare``
.. note:: You also can use ``glance`` as value
of :option:`--murano-packages-service` option or environment variable
:option:`MURANO_PACKAGES_SERVICE` for same behaviour
of ``--murano-packages-service`` option or environment variable
``MURANO_PACKAGES_SERVICE`` for same behaviour
+ View list of packages:
@ -125,7 +125,7 @@ specify where g-glare service is running.
GLARE_API_URL = 'http://<GLARE_API>:<GLARE_API_PORT>'
#. Set the ``GLARE_URL`` environment variable for python-muranoclient.
Alternatively, use the :option:`--glare-url` option in CLI.
Alternatively, use the ``--glare-url`` option in CLI.
.. code-block:: console

8
doc/source/appdev-guide/app_migrating/app_migrate_to_juno.rst
View File

@ -18,7 +18,7 @@ of your app.
For example:
::
.. code-block:: yaml
Workflow:
deploy:
@ -27,7 +27,7 @@ For example:
Should be changed to:
::
.. code-block:: yaml
Methods:
deploy:
@ -68,7 +68,7 @@ type. This change must be added to UI form definition in *app.name/UI/ui.yaml*.
For example, if you are going to install your application on Ubuntu, you need to
change:
::
.. code-block:: yaml
Application:
?:
@ -78,7 +78,7 @@ change:
to:
::
.. code-block:: yaml
Application:
?:

4
doc/source/appdev-guide/app_migrating/app_migrate_to_newton.rst
View File

@ -128,5 +128,5 @@ of objects destruction and let objects be aware of other objects destruction,
react to this event, including the ability to prevent other objects from
being destroyed.
Please refer to the documentation on how to use the garbage collector:
:ref:`garbage_collection`.
Please refer to the documentation on how to use the
:ref:`Garbage Collector <garbage_collection>`.

2
doc/source/appdev-guide/app_unit_tests.rst
View File

@ -75,7 +75,7 @@ the test cases, or a separate package. You can specify a class name to
execute all the tests located in it, or specify a particular test case name.
Authorization parameters can be provided in the murano configuration file, or
with higher priority :option:`-os-` parameters.
with higher priority ``-os-`` parameters.
Consider the following example of test execution for the Tomcat application.
Tests are located in the same package with application, but in a separate class

2
doc/source/appdev-guide/garbage_collection.rst
View File

@ -1,4 +1,4 @@
.. garbage_collection:
.. _garbage_collection:
=====================================
Garbage collection system in MuranoPL

10
doc/source/appdev-guide/murano_pl/actions.rst
View File

@ -40,7 +40,7 @@ occasionally will be no longer supported. Also, you cannot use both
The following example shows an action that returns an archive with a
configuration file:
::
.. code-block:: yaml
exportConfig:
Scope: Public
@ -62,7 +62,7 @@ Request:
Response:
.. code-block:: javascript
.. code-block:: json
{
"name": "SimpleVM",
@ -93,7 +93,7 @@ result of its execution will be returned.
Consider the following example of the static action that makes use both of
static class property and user's input as an argument:
::
.. code-block:: yaml
Name: Bar
@ -118,7 +118,7 @@ Request:
Request body:
.. code-block:: javascript
.. code-block:: json
{
"className": "ns.Bar",
@ -128,6 +128,6 @@ Request body:
Responce:
.. code-block:: javascript
.. code-block:: json
"Hello, John"

12
doc/source/appdev-guide/murano_pl/class_templ.rst
View File

@ -318,7 +318,9 @@ Default, if specified, must conform to a declared property contract.
If Default is not specified, then null is the default.
For properties that are references to other classes, Default can modify
a default value of the referenced objects. For example::
a default value of the referenced objects. For example:
.. code-block:: yaml
p:
Contract: $.class(MyClass)
@ -398,7 +400,9 @@ Unlike class properties Arguments may have a different set of Usages:
with keys being valid keyword strings and values matching a contract
of the argument.
Arguments example::
Arguments example:
.. code-block:: yaml
scaleRc:
Arguments:
@ -650,7 +654,7 @@ Object model, and a predefined method is executed on the root object.
Objects are serialized to JSON using the following template:
.. code-block:: yaml
.. code-block:: json
:linenos:
{
@ -695,4 +699,4 @@ There are two ways to specify references:
be defined elsewhere in an object tree. Object references distinguished
from strings having the same value by evaluating property contracts.
The former case would have ``$.class(Name)`` while the later - the
``$.string()`` contract.
``$.string()`` contract.

8
doc/source/appdev-guide/murano_pl/core_lib.rst
View File

@ -308,7 +308,9 @@ a logger name as the only parameter. It is a common recommendation to use full
class name as a logger name within that class. This convention avoids names
conflicts in logs and ensures a better logging subsystem configurability.
Logger class instantiation::
Logger class instantiation:
.. code-block:: yaml
$log: logger('io.murano.apps.activeDirectory.ActiveDirectory')
@ -340,7 +342,9 @@ There are several methods that fully correspond to the log levels you can use
for logging events. They are ``debug``, ``trace``, ``info``, ``warning``,
``error``, and ``critical``.
Logging example::
Logging example:
.. code-block:: yaml
$log.info('print my info message {message}', message=>message)

174
doc/source/appendix/articles/ad-ui.rst
View File

@ -1,174 +0,0 @@
.. _adUI:
=============================================
UI Definition Of Active Directory Application
=============================================
.. code-block:: yaml
Version: 2
Templates:
primaryController:
?:
type: io.murano.windows.activeDirectory.PrimaryController
host:
?:
type: io.murano.windows.Host
adminPassword: $.appConfiguration.adminPassword
name: generateHostname($.appConfiguration.unitNamingPattern, 1)
flavor: $.instanceConfiguration.flavor
image: $.instanceConfiguration.osImage
assignFloatingIp: $.appConfiguration.assignFloatingIP
secondaryController:
?:
type: io.murano.windows.activeDirectory.SecondaryController
host:
?:
type: io.murano.services.windows.Host
adminPassword: $.appConfiguration.adminPassword
name: generateHostname($.appConfiguration.unitNamingPattern, $index + 1)
flavor: $.instanceConfiguration.flavor
image: $.instanceConfiguration.osImage
Application:
?:
type: io.murano.windows.activeDirectory.ActiveDirectory
name: $.appConfiguration.name
primaryController: $primaryController
secondaryControllers: repeat($secondaryController, $.appConfiguration.dcInstances - 1)
Forms:
- appConfiguration:
fields:
- name: configuration
type: string
hidden: true
initial: standalone
- name: name
type: string
label: Domain Name
description: >-
Enter a desired name for a new domain. This name should fit to
DNS Domain Name requirements: it should contain
only A-Z, a-z, 0-9, (.) and (-) and should not end with a dash.
DNS server will be automatically set up on each of the Domain
Controller instances. Note: Only first 15 characters or characters
before first period is used as NetBIOS name.
minLength: 2
maxLength: 255
validators:
- expr:
regexpValidator: '^([0-9A-Za-z]|[0-9A-Za-z][0-9A-Za-z-]*[0-9A-Za-z])\.[0-9A-Za-z][0-9A-Za-z-]*[0-9A-Za-z]$'
message: >-
Only letters, numbers and dashes in the middle are
allowed. Period characters are allowed only when they
are used to delimit the components of domain style
names. Single-level domain is not
appropriate. Subdomains are not allowed.
- expr:
regexpValidator: '(^[^.]+$|^[^.]{1,15}\..*$)'
message: >-
NetBIOS name cannot be shorter than 1 symbol and
longer than 15 symbols.
- expr:
regexpValidator: '(^[^.]+$|^[^.]*\.[^.]{2,63}.*$)'
message: >-
DNS host name cannot be shorter than 2 symbols and
longer than 63 symbols.
helpText: >-
Just letters, numbers and dashes are allowed.
A dot can be used to create subdomains
- name: dcInstances
type: integer
label: Instance Count
description: >-
You can create several Active Directory instances by setting
instance number larger than one. One primary Domain Controller
and a few secondary DCs will be created.
minValue: 1
maxValue: 100
initial: 1
helpText: Enter an integer value between 1 and 100
- name: adminAccountName
type: string
label: Account Name
initial: Administrator
regexpValidator: '^[-\w]+$'
errorMessages:
invalid: 'Just letters, numbers, underscores and hyphens are allowed.'
- name: adminPassword
type: password
label: Administrator password
descriptionTitle: Passwords
description: >-
Windows requires strong password for service administration.
Your password should have at least one letter in each
register, a number and a special character. Password length should be
a minimum of 7 characters.
Once you forget your password you won't be able to
operate the service until recovery password would be entered. So it's
better for Recovery and Administrator password to be different.
- name: recoveryPassword
type: password
label: Recovery password
- name: assignFloatingIP
required: false
type: boolean
label: Assign Floating IP
description: >-
Select to true to assign floating IP automatically to Primary DC
initial: false
required: false
widgetMedia:
css: {all: ['muranodashboard/css/checkbox.css']}
- name: unitNamingPattern
type: string
label: Hostname template
description: >-
For your convenience all instance hostnames can be named
in the same way. Enter a name and use # character for incrementation.
For example, host# turns into host1, host2, etc. Please follow Windows
hostname restrictions.
required: false
regexpValidator: '^(([a-zA-Z0-9#][a-zA-Z0-9-#]*[a-zA-Z0-9#])\.)*([A-Za-z0-9#]|[A-Za-z0-9#][A-Za-z0-9-#]*[A-Za-z0-9#])$'
# FIXME: does not work for # turning into 2-digit numbers
maxLength: 15
helpText: Optional field for a machine hostname template
# temporaryHack
widgetMedia:
js: ['muranodashboard/js/support_placeholder.js']
css: {all: ['muranodashboard/css/support_placeholder.css']}
validators:
# if unitNamingPattern is given and dcInstances > 1, then '#' should occur in unitNamingPattern
- expr: $.appConfiguration.dcInstances < 2 or not $.appConfiguration.unitNamingPattern.bool() or '#' in $.appConfiguration.unitNamingPattern
message: Incrementation symbol "#" is required in the Hostname template
- instanceConfiguration:
fields:
- name: title
type: string
required: false
hidden: true
descriptionTitle: Instance Configuration
description: Specify some instance parameters on which service would be created.
- name: flavor
type: flavor
label: Instance flavor
description: >-
Select registered in OpenStack flavor. Consider that service performance
depends on this parameter.
required: false
- name: osImage
type: image
imageType: windows
label: Instance image
description: >-
Select valid image for a service. Image should already be prepared and
registered in glance.
- name: availabilityZone
type: azone
label: Availability zone
description: Select availability zone where service would be installed.
required: false

6
doc/source/appendix/articles/specification/murano-repository.rst
View File

@ -136,7 +136,7 @@ See the example of multipart/form-data request, It should contain two parts - te
**Request (multipart/form-data)**
::
.. code-block:: none
Content-type: multipart/form-data, boundary=AaB03x
Content-Length: $requestlen
@ -167,7 +167,7 @@ See the example of multipart/form-data request, It should contain two parts - te
**Response 200 (application/json)**
::
.. code-block:: json
{
"updated": "2014-04-03T13:00:13",
@ -583,7 +583,7 @@ Delete category
| Method | URI | Description |
+==========+===================================+=============================+
| DELETE | /catalog/categories/<category_id> | Delete category with |
| | | specified ID |
| | | specified ID |
+----------+-----------------------------------+-----------------------------+
*Parameters:*

111
doc/source/appendix/articles/telnet.rst
View File

@ -1,111 +0,0 @@
.. _TelnetUI:
===================================
UI Definition of telnet application
===================================
.. code-block:: yaml
Version: 2
Templates:
instance:
?:
type: io.murano.resources.LinuxMuranoInstance
name: generateHostname($.appConfiguration.unitNamingPattern, 1)
flavor: $.instanceConfiguration.flavor
image: $.instanceConfiguration.osImage
keyname: $.instanceConfiguration.keyPair
assignFloatingIp: $.appConfiguration.assignFloatingIP
Application:
?:
type: io.murano.apps.linux.Telnet
name: $.appConfiguration.name
instance: $instance
Forms:
- appConfiguration:
fields:
- name: title
type: string
required: false
hidden: true
description: Telnet is a service that allows a Telnet client to connect across a network and access a command session
- name: name
type: string
label: Application Name
description: >-
Enter a desired name for the application. Just A-Z, a-z, 0-9, dash and
underline are allowed.
minLength: 2
maxLength: 64
regexpValidator: '^[-\w]+$'
errorMessages:
invalid: Just letters, numbers, underscores and hyphens are allowed.
helpText: Just letters, numbers, underscores and hyphens are allowed.
- name: dcInstances
type: integer
hidden: true
initial: 1
- name: assignFloatingIP
type: boolean
label: Assign Floating IP
description: >-
Select to true to assign floating IP automatically
initial: false
required: false
widgetMedia:
css: {all: ['muranodashboard/css/checkbox.css']}
- name: unitNamingPattern
type: string
label: Hostname
description: >-
For your convenience instance hostname can be specified.
Enter a name or leave blank for random name generation.
required: false
regexpValidator: '^(([a-zA-Z0-9#][a-zA-Z0-9-#]*[a-zA-Z0-9#])\.)*([A-Za-z0-9#]|[A-Za-z0-9#][A-Za-z0-9-#]*[A-Za-z0-9#])$'
helpText: Optional field for a machine hostname
# temporaryHack
widgetMedia:
js: ['muranodashboard/js/support_placeholder.js']
css: {all: ['muranodashboard/css/support_placeholder.css']}
validators:
# if unitNamingPattern is given and dcInstances > 1, then '#' should occur in unitNamingPattern
- expr: $.appConfiguration.dcInstances < 2 or not $.appConfiguration.unitNamingPattern.bool() or '#' in $.appConfiguration.unitNamingPattern
message: Incrementation symbol "#" is required in the Hostname template
- instanceConfiguration:
fields:
- name: title
type: string
required: false
hidden: true
description: Specify some instance parameters on which the application would be created
- name: flavor
type: flavor
label: Instance flavor
description: >-
Select registered in OpenStack flavor. Consider that application performance
depends on this parameter.
required: false
- name: osImage
type: image
imageType: linux
label: Instance image
description: >-
Select valid image for the application. Image should have Murano agent installed and
registered in Glance.
- name: keyPair
type: keypair
label: Key Pair
description: >-
Select the Key Pair to control access to instances. You can login to
instances using this KeyPair after application deployment
required: false
- name: availabilityZone
type: azone
label: Availability zone
description: Select availability zone where the application would be installed.
required: false

4
doc/source/appendix/articles/telnet_example.rst
View File

@ -1,4 +1,6 @@
.. _telnet-example:
:orphan:
.. _telnet_example:
Telnet Example
--------------

6
doc/source/appendix/articles/workflow.rst
View File

@ -27,10 +27,10 @@ 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 <telnet-example>` only one class is explicitly
the :ref:`Telnet example <telnet_example>` only one class is explicitly
required; the telnet application definition.
The :ref:`Telnet class definition <telnet-example>` refers to several other
The :ref:`Telnet class definition <telnet_example>` 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:`status-reporter`
@ -60,7 +60,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 <telnet-example>` (under *Workflow*), the workflow
In the :ref:`Telnet example <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

6
doc/source/enduser-guide/userguide/deploying_using_cli.rst
View File

@ -56,7 +56,7 @@ Create a configuration session
Murano uses configuration sessions to allow several users to edit and configure
the same environment concurrently. Most of environment-related commands
require the :option:`--session-id` parameter. For convenience, this guide
require the ``--session-id`` parameter. For convenience, this guide
refers to session ID as ``$SESS_ID``.
To create a configuration session, use the
@ -127,7 +127,7 @@ Verify your object model
To verify whether your object model is correct, check the environment by
running the :command:`environment-show` command with the
:option:`--session-id` parameter:
``--session-id`` parameter:
.. code-block:: console
@ -172,7 +172,7 @@ You can later use the :command:`murano environment-show` command to
track the deployment status.
To view the deployed applications of a particular environment, use the
:command:`murano environment-show` command with the :option:`--only-apps`
:command:`murano environment-show` command with the ``--only-apps``
parameter and specifying the environment ID:
.. code-block:: console

2
doc/source/first-app/source/index.rst
View File

@ -2,6 +2,8 @@
My first Murano App getting started guide
=========================================
.. include:: ../README.rst
Contents
~~~~~~~~

12
doc/source/index.rst
View File

@ -62,6 +62,16 @@ client.
administrator-guide/admin_index
First App Guide
~~~~~~~~~~~~~~~
A guide for developing your first Murano application.
.. toctree::
:maxdepth: 1
first-app/source/index
Application Developer Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -91,4 +101,4 @@ Other Documentation
:maxdepth: 1
appendix/appendix_index
appendix/articles/articles_index
appendix/articles/articles_index

1
setup.cfg
View File

@ -84,6 +84,7 @@ murano_policy_modify_actions =
all_files = 1
build-dir = doc/build
source-dir = doc/source
warning-is-error = 1
[egg_info]
tag_build =