Mark doc warnings as errors

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

doc/source/administrator-guide/admin_troubleshooting.rst

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

doc/source/administrator-guide/configure_cloud_foundry_service_broker.rst

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

doc/source/administrator-guide/prepare_lab.rst

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

doc/source/administrator-guide/using_glare.rst

@@ -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
+             of ``--murano-packages-service`` option or environment variable
-             :option:`MURANO_PACKAGES_SERVICE` for same behaviour
+             ``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
 

doc/source/appdev-guide/app_migrating/app_migrate_to_juno.rst

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

doc/source/appdev-guide/app_migrating/app_migrate_to_newton.rst

@@ -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:
+Please refer to the documentation on how to use the
-:ref:`garbage_collection`.
+:ref:`Garbage Collector <garbage_collection>`.

doc/source/appdev-guide/app_unit_tests.rst

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

doc/source/appdev-guide/garbage_collection.rst

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

doc/source/appdev-guide/murano_pl/actions.rst

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

doc/source/appdev-guide/murano_pl/class_templ.rst

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

doc/source/appdev-guide/murano_pl/core_lib.rst

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

doc/source/appendix/articles/ad-ui.rst

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

doc/source/appendix/articles/specification/murano-repository.rst

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

doc/source/appendix/articles/telnet.rst

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

doc/source/appendix/articles/telnet_example.rst

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

doc/source/appendix/articles/workflow.rst

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

doc/source/enduser-guide/userguide/deploying_using_cli.rst

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

doc/source/first-app/source/index.rst

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

doc/source/index.rst

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

setup.cfg

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