Merge "Add doc8 rule and check doc/source files"

doc/source/admin/upgrade_guide.rst

@@ -7,9 +7,9 @@ Database upgrade
 The migrations in ``alembic_migrations/versions`` contain the changes needed to
 migrate between Mistral database revisions. A migration occurs by executing a
 script that details the changes needed to upgrade the database. The migration
-scripts are ordered so that multiple scripts can run sequentially. The scripts are
+scripts are ordered so that multiple scripts can run sequentially. The scripts
-executed by Mistral's migration wrapper which uses the Alembic library to manage
+are executed by Mistral's migration wrapper which uses the Alembic library to
-the migration. Mistral supports migration from Kilo or later.
+manage the migration. Mistral supports migration from Kilo or later.
 
 You can upgrade to the latest database version via:
 ::

doc/source/api/v2.rst

@@ -1,8 +1,8 @@
 V2 API
 ======
 
-This API describes the ways of interacting with Mistral service via HTTP protocol
+This API describes the ways of interacting with Mistral service via
-using Representational State Transfer concept (ReST).
+HTTP protocol using Representational State Transfer concept (ReST).
 
 
 Basics
@@ -17,7 +17,9 @@ Currently this API relies on JSON to represent states of REST resources.
 Error states
 ^^^^^^^^^^^^
 
-The common HTTP Response Status Codes (https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.
+The common HTTP Response Status Codes
+(https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md)
+are used.
 
 Application root [/]
 ^^^^^^^^^^^^^^^^^^^^
@@ -114,9 +116,9 @@ belongs to a particular execution.
 Action Executions
 -----------------
 
-When a Task starts Mistral creates a set of Action Executions. So Action Execution
+When a Task starts Mistral creates a set of Action Executions. So Action
-is an instance of an action call described in a Workflow Task that belongs to a
+Execution is an instance of an action call described in a Workflow Task that
-particular execution.
+belongs to a particular execution.
 
 
 .. autotype:: mistral.api.controllers.v2.resources.ActionExecution
@@ -134,10 +136,10 @@ particular execution.
 Cron Triggers
 -------------
 
-Cron trigger is an object that allows to run Mistral workflows according to a time
+Cron trigger is an object that allows to run Mistral workflows according to
-pattern (Unix crontab patterns format). Once a trigger is created it will run a
+a time pattern (Unix crontab patterns format). Once a trigger is created it
-specified workflow according to its properties: pattern, first_execution_time and
+will run a specified workflow according to its properties: pattern,
-remaining_executions.
+first_execution_time and remaining_executions.
 
 
 .. autotype:: mistral.api.controllers.v2.resources.CronTrigger
@@ -198,15 +200,15 @@ Services
 
 Through service management API, system administrator or operator can retrieve
 Mistral services information of the system, including service group and service
-identifier. The internal implementation of this feature make use of tooz library,
+identifier. The internal implementation of this feature make use of tooz
-which needs coordinator backend(the most commonly used at present is Zookeeper)
+library, which needs coordinator backend(the most commonly used at present is
-installed, please refer to tooz official documentation for more detailed
+Zookeeper) installed, please refer to tooz official documentation for more
-instruction.
+detailed instruction.
 
-There are three service groups according to Mistral architecture currently, namely
+There are three service groups according to Mistral architecture currently,
-api_group, engine_group and executor_group. The service identifier contains name
+namely api_group, engine_group and executor_group. The service identifier
-of the host the service is running on and the process identifier of the service on
+contains name of the host the service is running on and the process identifier
-that host.
+of the service on that host.
 
 .. autotype:: mistral.api.controllers.v2.resources.Service
    :members:
@@ -220,8 +222,8 @@ that host.
 Validation
 ----------
 
-Validation endpoints allow to check correctness of workbook, workflow and ad-hoc
+Validation endpoints allow to check correctness of workbook, workflow and
-action Workflow Language without having to upload them into Mistral.
+ad-hoc action Workflow Language without having to upload them into Mistral.
 
 **POST /v2/workbooks/validation**
   Validate workbook content (Workflow Language grammar and semantics).
@@ -232,5 +234,5 @@ action Workflow Language without having to upload them into Mistral.
 **POST /v2/actions/validation**
   Validate ad-hoc action content (Workflow Language grammar and semantics).
 
-These endpoints expect workbook, workflow or ad-hoc action  text (Workflow Language) correspondingly
+These endpoints expect workbook, workflow or ad-hoc action text
-in a request body.
+(Workflow Language) correspondingly in a request body.

doc/source/architecture.rst

@@ -40,10 +40,10 @@ The API server exposes REST API to operate and monitor the workflow executions.
 Engine
 ------
 
-The Engine picks up the workflows from the workflow queue. It handles the control
+The Engine picks up the workflows from the workflow queue. It handles the
-and dataflow of workflow executions. It also computes which tasks are ready and
+control and dataflow of workflow executions. It also computes which tasks
-places them in a task queue. It passes the data from task to task, deals with
+are ready and places them in a task queue. It passes the data from task to
-condition transitions, etc.
+task, deals with condition transitions, etc.
 
 Task Executors
 --------------

doc/source/configuration/index.rst

@@ -9,7 +9,9 @@ directory.
 
 #. Generate *mistral.conf* (if it does not already exist)::
 
-    $ oslo-config-generator --config-file tools/config/config-generator.mistral.conf --output-file /etc/mistral/mistral.conf
+    $ oslo-config-generator \
+      --config-file tools/config/config-generator.mistral.conf \
+      --output-file /etc/mistral/mistral.conf
 
 #. Edit file **/etc/mistral/mistral.conf**.
 
@@ -24,8 +26,9 @@ directory.
     admin_password = <password>
     admin_tenant_name = <tenant>
 
-#. Mistral can be also configured to authenticate with Keycloak server via OpenID Connect protocol.
+#. Mistral can be also configured to authenticate with Keycloak server
-   In order to enable Keycloak authentication the following section should be in the config file::
+   via OpenID Connect protocol. In order to enable Keycloak authentication
+   the following section should be in the config file::
 
     auth_type = keycloak-oidc
 
@@ -33,11 +36,11 @@ directory.
     auth_url = https://<Keycloak-server-host>:<Keycloak-server-port>/auth
 
    Property 'auth_type' is assigned to 'keystone' by default.
-   If SSL/TLS verification needs to be disabled then 'insecure = True' should also be added
+   If SSL/TLS verification needs to be disabled then 'insecure = True'
-   under [keycloak_oidc] group.
+   should also be added under [keycloak_oidc] group.
 
-#. If you want to configure SSL for Mistral API server, provide following options
+#. If you want to configure SSL for Mistral API server, provide following
-   in config file::
+   options in config file::
 
     [api]
     enable_ssl_api = True
@@ -57,7 +60,8 @@ directory.
    and Mistral endpoints on Keystone::
 
     $ MISTRAL_URL="http://[host]:[port]/v2"
-    $ openstack service create workflowv2 --name mistral --description 'OpenStack Workflow service'
+    $ openstack service create workflowv2 --name mistral \
+      --description 'OpenStack Workflow service'
     $ openstack endpoint create workflowv2 public $MISTRAL_URL
     $ openstack endpoint create workflowv2 internal $MISTRAL_URL
     $ openstack endpoint create workflowv2 admin $MISTRAL_URL
@@ -68,10 +72,11 @@ directory.
     transport_url = rabbit://<user_id>:<password>@<host>:5672/
 
 #. Configure database. **SQLite can't be used in production**. Use *MySQL* or
-   *PostgreSQL* instead. Here are the steps how to connect *MySQL* DB to Mistral:
+   *PostgreSQL* instead. Here are the steps how to connect *MySQL* DB to
+   Mistral:
 
-   Make sure you have installed **mysql-server** package on your database machine
+   Make sure you have installed **mysql-server** package on your database
-   (it can be your Mistral machine as well).
+   machine (it can be your Mistral machine as well).
 
    Install MySQL driver for python::
 
@@ -95,13 +100,14 @@ directory.
     connection = postgresql://<user>:<password>@<database-host>:5432/mistral
 
 #. **If you are not using OpenStack, skip this item.**
-   Update mistral/actions/openstack/mapping.json file which contains all allowed
+   Update mistral/actions/openstack/mapping.json file which contains all
-   OpenStack actions, according to the specific client versions of OpenStack
+   allowed OpenStack actions, according to the specific client versions
-   projects in your deployment. Please find more detailed information in
+   of OpenStack projects in your deployment. Please find more detailed
-   tools/get_action_list.py script.
+   information in tools/get_action_list.py script.
 
 #. Configure Task affinity feature if needed. It is needed for distinguishing
-   either single task executor or one task executor from group of task executors::
+   either single task executor or one task executor from group of task
+   executors::
 
     [executor]
     host = my_favorite_executor
@@ -121,9 +127,12 @@ directory.
      [oslo_policy]
      policy_file = <path-of-policy.json file>
 
-    Default policy.json file is in ``mistral/etc/``. For more details see `policy.json file <https://docs.openstack.org/ocata/config-reference/policy-json-file.html>`_.
+   Default policy.json file is in ``mistral/etc/``.
+   For more details see `policy.json file
+   <https://docs.openstack.org/ocata/config-reference/policy-json-file.html>`_.
 
-#. After that try to run mistral engine and see it is running without any error::
+#. After that try to run mistral engine and see it is running without
+   any error::
 
      $ mistral-server --config-file <path-to-config> --server engine
 

doc/source/contributor/asynchronous_actions.rst

@@ -8,35 +8,39 @@ Concept
 
 .. image:: /img/Mistral_actions.png
 
-During a workflow execution Mistral eventually runs actions. Action is a particular
+During a workflow execution Mistral eventually runs actions. Action
-function (or a piece of work) that a workflow task is associated to.
+is a particular function (or a piece of work) that a workflow task
+is associated to.
 
 Actions can be synchronous and asynchronous.
 
-Synchronous actions are actions that get completed without a 3rd party, i.e. by
+Synchronous actions are actions that get completed without a 3rd party,
-Mistral itself. When Mistral engine schedules to run a synchronous action it sends
+i.e. by Mistral itself. When Mistral engine schedules to run a synchronous
-its definition and parameters to Mistral executor, then executor runs it and upon
+action it sends its definition and parameters to Mistral executor, then
-its completion sends a result of the action back to Mistral engine.
+executor runs it and upon its completion sends a result of the action back
+to Mistral engine.
 
 In case of asynchronous actions executor doesn't send a result back to Mistral.
-In fact, the concept of asynchronous action assumes that a result won't be known
+In fact, the concept of asynchronous action assumes that a result won't be
-at a time when executor is running it. It rather assumes that action will just
+known at a time when executor is running it. It rather assumes that action
-delegate actual work to a 3rd party which can be either a human or a computer
+will just delegate actual work to a 3rd party which can be either a human or
-system (e.g. a web service). So an asynchronous action's run() method is supposed
+a computer system (e.g. a web service). So an asynchronous action's run()
-to just send a signal to something that is capable of doing required job.
+method is supposed to just send a signal to something that is capable of
+doing required job.
 
-Once the 3rd party has done the job it takes responsibility to send result of
+Once the 3rd party has done the job it takes responsibility to send result
-the action back to Mistral via Mistral API. Effectively, the 3rd party just needs
+of the action back to Mistral via Mistral API. Effectively, the 3rd party just
-to update the state of corresponding action execution object. To make it possible
+needs to update the state of corresponding action execution object. To make it
-it must know corresponding action execution id.
+possible it must know corresponding action execution id.
 
-It's worth noting that from Mistral engine perspective the schema is essentially
+It's worth noting that from Mistral engine perspective the schema is
-the same in case of synchronous and asynchronous actions. If action is synchronous,
+essentially the same in case of synchronous and asynchronous actions.
-then executor immediately sends a result back with RPC mechanism (most often,
+If action is synchronous, then executor immediately sends a result back
-a message queue as a transport) to Mistral engine after action completion. But
+with RPC mechanism (most often, a message queue as a transport) to Mistral
-engine itself is not waiting anything proactively, its architecture is fully on
+engine after action completion. But engine itself is not waiting anything
-asynchronous messages. So in case of asynchronous action the only change is that
+proactively, its architecture is fully on asynchronous messages. So in case
-executor is not responsible for sending action result, something else takes over.
+of asynchronous action the only change is that executor is not responsible
+for sending action result, something else takes over.
 
 Let's see what we need to keep in mind when working with asynchronous actions.
 
@@ -44,20 +48,21 @@ Let's see what we need to keep in mind when working with asynchronous actions.
 How to
 ******
 
-Currently, Mistral comes with one asynchronous action out of the box, "mistral_http".
+Currently, Mistral comes with one asynchronous action out of the box,
-There's also "async_noop" action that is also asynchronous but it's mostly useful
+"mistral_http".
-for testing purposes because it does nothing. "mistral_http" is an asynchronous
+There's also "async_noop" action that is also asynchronous but it's mostly
-version of action "http" sending HTTP requests. Asynchrony is controlled by
+useful for testing purposes because it does nothing. "mistral_http" is an
-action's method is_sync() which should return *True* for synchronous actions and
+asynchronous version of action "http" sending HTTP requests. Asynchrony is
-*False* for asynchronous.
+controlled by action's method is_sync() which should return *True* for
+synchronous actions and *False* for asynchronous.
 
 Let's see how "mistral_http" action works and how to use it step by step.
 
-We can imagine that we have a simple web service playing a role of 3rd party system
+We can imagine that we have a simple web service playing a role of 3rd party
-mentioned before accessible at http://my.webservice.com. And if we send an HTTP
+system mentioned before accessible at http://my.webservice.com. And if we send
-request to that url then our web service will do something useful. To keep it
+an HTTP request to that url then our web service will do something useful.
-simple, let's say our web service just calculates a sum of two numbers provided
+To keep it simple, let's say our web service just calculates a sum of two
-as request parameters "a" and "b".
+numbers provided as request parameters "a" and "b".
 
 1. Workflow example
 ===================
@@ -76,14 +81,16 @@ as request parameters "a" and "b".
                a: 1
                b: 2
 
-So our workflow has just one task "one_plus_two" that sends a request to our web
+So our workflow has just one task "one_plus_two" that sends a request to
-service and passes parameters "a" and "b" in a query string. Note that we specify
+our web service and passes parameters "a" and "b" in a query string. Note
-"url" right after action name but "params" in a special section "input". This is
+that we specify "url" right after action name but "params" in a special
-because there's no one-line syntax for dictionaries currently in Mistral. But both
+section "input". This is because there's no one-line syntax for dictionaries
-"url" and "params" are basically just parameters of action "mistral_http".
+currently in Mistral. But both "url" and "params" are basically just parameters
+of action "mistral_http".
 
-It is important to know that when "mistral_http" action sends a request it includes
+It is important to know that when "mistral_http" action sends a request it
-special HTTP headers that help identify action execution object. These headers are:
+includes special HTTP headers that help identify action execution object.
+These headers are:
 
 - **Mistral-Workflow-Name**
 - **Mistral-Workflow-Execution-Id**
@@ -91,25 +98,27 @@ special HTTP headers that help identify action execution object. These headers a
 - **Mistral-Action-Execution-Id**
 - **Mistral-Callback-URL**
 
-The most important one is "Mistral-Action-Execution-Id" which contains an id of
+The most important one is "Mistral-Action-Execution-Id" which contains an id
-action execution that we need to calculate result for. Using that id a 3rd party
+of action execution that we need to calculate result for. Using that id a 3rd
-can deliver a result back to Mistral once it's calculated. If a 3rd party is a
+party can deliver a result back to Mistral once it's calculated. If a 3rd party
-computer system it can just call Mistral API via HTTP using header
+is a computer system it can just call Mistral API via HTTP using header
 "Mistral-Callback-URL" which contains a base URL. However, a human can also do
 it, the simplest way is just to use Mistral CLI.
 
-Of course, this is a practically meaningless example. It doesn't make sense to use
+Of course, this is a practically meaningless example. It doesn't make sense to
-asynchronous actions for simple arithmetic operations. Real examples when asynchronous
+use asynchronous actions for simple arithmetic operations. Real examples when
-actions are needed may include:
+asynchronous actions are needed may include:
 
-- **Analysis of big data volumes**. E.g. we need to run an external reporting tool.
+- **Analysis of big data volumes**. E.g. we need to run an external
-- **Human interaction**. E.g. an administrator needs to approve allocation of resources.
+  reporting tool.
+- **Human interaction**. E.g. an administrator needs to approve allocation of
+  resources.
 
-In general, this can be anything that takes significant time, such as hours, days
+In general, this can be anything that takes significant time, such as hours,
-or weeks. Sometimes duration of a job may be even unpredictable (it's reasonable
+days or weeks. Sometimes duration of a job may be even unpredictable (it's
-though to try to limit such jobs with timeout policy in practice).
+reasonable though to try to limit such jobs with timeout policy in practice).
-The key point here is that Mistral shouldn't try to wait for completion of such
+The key point here is that Mistral shouldn't try to wait for completion of
-job holding some resources needed for that in memory.
+such job holding some resources needed for that in memory.
 
 An important aspect of using asynchronous actions is that even when we interact
 with 3rd party computer systems a human can still trigger action completion by

doc/source/contributor/extending_yaql.rst

@@ -6,7 +6,8 @@ How to write a custom YAQL function
 Tutorial
 ********
 
-1. Create a new Python project, an empty folder, containing a basic ``setup.py`` file.
+1. Create a new Python project, an empty folder, containing a basic
+``setup.py`` file.
 
 .. code-block:: bash
 

doc/source/contributor/troubleshooting.rst

@@ -12,7 +12,8 @@ The following instructions should get you sorted to debug both on the same run.
 
 Set PyCharm debug settings:
 
-1. Under File > Settings > Languages and Framework > Django -  Enter the following:
+1. Under File > Settings > Languages and Framework > Django -
+Enter the following:
 
   a. Check "Enable Django Support"
   b. Django project root: your file system path to Horizon project root
@@ -61,7 +62,8 @@ After a successful login bring the port back - it will continue your session.
 **Further notes**
 
 - If you need help with PyCharm and general debugging, please refer to:
-  `JetBrains PyCharm developer guide <https://www.jetbrains.com/pycharm/help/debugging.html.>`_
+  `JetBrains PyCharm developer guide
+  <https://www.jetbrains.com/pycharm/help/debugging.html.>`_
 
 - If you would like to manually restart the apache server,
   open a terminal and run::

doc/source/install/dashboard_guide.rst

@@ -2,16 +2,18 @@
 Mistral Dashboard Installation Guide
 ====================================
 
-Mistral dashboard is the plugin for Horizon where it is easily possible to control
+Mistral dashboard is the plugin for Horizon where it is easily possible to
-mistral objects by interacting with web user interface.
+control mistral objects by interacting with web user interface.
 
 Setup Instructions
 ------------------
-This instruction assumes that Horizon is already installed and it's installation
+This instruction assumes that Horizon is already installed and it's
-folder is <horizon>. Detailed information on how to install Horizon can be
+installation folder is <horizon>. Detailed information on how to install
-found at `Horizon Installation <https://docs.openstack.org/horizon/latest/contributor/quickstart.html#setup>`_
+Horizon can be found at `Horizon Installation
+<https://docs.openstack.org/horizon/latest/contributor/quickstart.html#setup>`_
 
-The installation folder of Mistral Dashboard will be referred to as <mistral-dashboard>.
+The installation folder of Mistral Dashboard will be referred to as
+<mistral-dashboard>.
 
 The following should get you started:
 
@@ -23,13 +25,15 @@ The following should get you started:
 
     $ sudo pip install -e <mistral-dashboard>
 
- Or if you're planning to run Horizon server in a virtual environment (see below)::
+ Or if you're planning to run Horizon server in a virtual environment
+ (see below)::
 
     $ tox -evenv -- pip install -e ../mistral-dashboard/
 
  and then::
 
-    $ cp -b <mistral-dashboard>/mistraldashboard/enabled/_50_mistral.py <horizon>/openstack_dashboard/local/enabled/_50_mistral.py
+    $ cp -b <mistral-dashboard>/mistraldashboard/enabled/_50_mistral.py \
+      <horizon>/openstack_dashboard/local/enabled/_50_mistral.py
 
 3. Since Mistral only supports Identity v3, you must ensure that the dashboard
    points the proper OPENSTACK_KEYSTONE_URL in
@@ -49,7 +53,8 @@ The following should get you started:
 
     $ sudo service apache2 restart
 
- or run the development server (in case you have decided to use local horizon)::
+ or run the development server
+ (in case you have decided to use local horizon)::
 
     $ cd ../horizon/
     $ tox -evenv -- python manage.py runserver

doc/source/install/installation_guide.rst

@@ -21,8 +21,8 @@ The list of needed packages is shown below:
 
 In case of Ubuntu, just run::
 
-    $ apt-get install python-dev python-setuptools python-pip libffi-dev libxslt1-dev \
+    $ apt-get install python-dev python-setuptools python-pip libffi-dev \
-      libxml2-dev libyaml-dev libssl-dev
+      libxslt1-dev libxml2-dev libyaml-dev libssl-dev
 
 **NOTE:** **Mistral can be used without authentication at all or it can work
 with OpenStack.** In case of OpenStack, it works **only on Keystone v3**, make
@@ -31,7 +31,8 @@ sure **Keystone v3** is installed.
 Installation
 ------------
 
-**NOTE**: If it is needed to install Mistral using devstack, please refer to :doc:`Mistral Devstack Installation </contributor/devstack>`
+**NOTE**: If it is needed to install Mistral using devstack, please refer to
+:doc:`Mistral Devstack Installation </contributor/devstack>`
 
 First of all, clone the repo and go to the repo directory::
 
@@ -63,20 +64,20 @@ or::
     $ pip install -r requirements.txt
     $ python setup.py install
 
-**NOTE**: Differences *pip install -e* and *setup.py install*. **pip install -e**
+**NOTE**: Differences *pip install -e* and *setup.py install*.
-works very similarly to **setup.py install** or the EasyInstall tool, except
+**pip install -e** works very similarly to **setup.py install** or the
-that it doesn’t actually install anything. Instead, it creates a special
+EasyInstall tool, except that it doesn’t actually install anything.
-.egg-link file in the deployment directory, that links to your project’s
+Instead, it creates a special .egg-link file in the deployment directory,
-source code.
+that links to your project’s source code.
 
 Before the first run
 --------------------
 
-After installation you will see **mistral-server** and **mistral-db-manage** commands
+After installation you will see **mistral-server** and **mistral-db-manage**
-in your environment, either in system or virtual environment.
+commands in your environment, either in system or virtual environment.
 
-**NOTE**: In case of using **virtualenv**, all Mistral related commands available via
+**NOTE**: In case of using **virtualenv**, all Mistral related commands
-**tox -evenv --**. For example, *mistral-server* is available via
+available via **tox -evenv --**. For example, *mistral-server* is available via
 *tox -evenv -- mistral-server*.
 
 **mistral-db-manage** command can be used for migrations.
@@ -91,11 +92,13 @@ workflows which Mistral provides for all Mistral users.::
 
     $ mistral-db-manage --config-file <path-to-mistral.conf> populate
 
-For more detailed information about *mistral-db-manage* script please see :doc:`Mistral Upgrade Guide </admin/upgrade_guide>`.
+For more detailed information about *mistral-db-manage* script please
+see :doc:`Mistral Upgrade Guide </admin/upgrade_guide>`.
 
 **NOTE**: For users who want a dry run with **SQLite** database backend(not
 used in production), *mistral-db-manage* is not recommended for database
-initialization because of `SQLite limitations <http://www.sqlite.org/omitted.html>`_.
+initialization because of
+`SQLite limitations <http://www.sqlite.org/omitted.html>`_.
 Please use sync_db script described below instead for database initialization.
 
 **If you use virtualenv**::
@@ -122,7 +125,8 @@ To run Mistral Engine perform the following command in a shell::
 
 Running Mistral Task Executors
 ------------------------------
-To run Mistral Task Executor instance perform the following command in a shell::
+To run Mistral Task Executor instance perform the following command
+in a shell::
 
     $ mistral-server --server executor --config-file <path-to-mistral.conf>
 
@@ -131,8 +135,8 @@ running so that workflow tasks are processed by Mistral.
 
 Running Multiple Mistral Servers Under the Same Process
 -------------------------------------------------------
-To run more than one server (API, Engine, or Task Executor) on the same process,
+To run more than one server (API, Engine, or Task Executor) on the same
-perform the following command in a shell::
+process, perform the following command in a shell::
 
     $ mistral-server --server api,engine --config-file <path-to-mistral.conf>
 
@@ -146,13 +150,15 @@ because the "fake" transport is using an in process queue.
 
 Mistral And Docker
 ------------------
-Please first refer `installation steps for docker <https://docs.docker.com/installation/>`_.
+Please first refer
+`installation steps for docker <https://docs.docker.com/installation/>`_.
 To build the image from the mistral source, change directory to the root
 directory of the Mistral git repository and run::
 
     $ docker build -t <Name of image> .
 
-In case you want pre-built image, you can download it from `openstack tarballs source <https://tarballs.openstack.org/mistral/images/mistral-docker.tar.gz>`_.
+In case you want pre-built image, you can download it from `openstack tarballs
+source <https://tarballs.openstack.org/mistral/images/mistral-docker.tar.gz>`_.
 
 To load this image to docker registry, please run following command::
 
@@ -163,7 +169,8 @@ directory. For persistence of these data, you may want to keep this directory
 outside of the container. This may be done by the following steps::
 
     $ sudo mkdir '<user-defined-directory>'
-    $ docker run -it -v '<user-defined-directory>':/home/mistral <Name of image>
+    $ docker run -it -v \
+      '<user-defined-directory>':/home/mistral <Name of image>
 
 More about docker: https://www.docker.com/
 

doc/source/install/mistralclient_guide.rst

@@ -24,13 +24,15 @@ have auth variables::
     $ export OS_TENANT_NAME=tenant
     $ export OS_USERNAME=admin
     $ export OS_PASSWORD=secret
-    $ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2  (optional, by default URL=http://localhost:8989/v2)
+    $ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2
+      ( optional, by default URL=http://localhost:8989/v2)
 
 and in the case when you are authenticating against keystone over https::
 
     $ export OS_CACERT=<path_to_ca_cert>
 
-.. note:: In client, we can use both Keystone auth versions - v2.0 and v3. But server supports only v3.
+.. note:: In client, we can use both Keystone auth versions - v2.0 and v3.
+          But server supports only v3.
 
 You can see the list of available commands by typing::
 
@@ -43,7 +45,8 @@ To make sure Mistral client works, type::
 Configure authentication against Keycloak
 -----------------------------------------
 
-Mistral also supports authentication against Keycloak server via OpenID Connect protocol.
+Mistral also supports authentication against Keycloak server via OpenID Connect
+protocol.
 In order to use it on the client side the environment should look as follows::
 
     $ export MISTRAL_AUTH_TYPE=keycloak-oidc
@@ -53,20 +56,25 @@ In order to use it on the client side the environment should look as follows::
     $ export OS_PASSWORD=secret
     $ export OPENID_CLIENT_ID=my_keycloak_client
     $ export OPENID_CLIENT_SECRET=my_keycloak_client_secret
-    $ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2  (optional, by default URL=http://localhost:8989/v2)
+    $ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2
+     (optional, by default URL=http://localhost:8989/v2)
 
-.. note:: Variables OS_TENANT_NAME, OS_USERNAME, OS_PASSWORD are used for both Keystone and Keycloak
+.. note:: Variables OS_TENANT_NAME, OS_USERNAME, OS_PASSWORD are used for
-    authentication. OS_TENANT_NAME in case of Keycloak needs to correspond a Keycloak realm. Unlike
+    both Keystone and Keycloak authentication. OS_TENANT_NAME in case of
-    Keystone, Keycloak requires to register a client that access some resources (Mistral server in
+    Keycloak needs to correspond a Keycloak realm. Unlike Keystone, Keycloak
-    our case) protected by Keycloak in advance. For this reason, OPENID_CLIENT_ID and
+    requires to register a client that access some resources (Mistral server in
-    OPENID_CLIENT_SECRET variables should be assigned with correct values as registered in Keycloak.
+    our case) protected by Keycloak in advance. For this reason,
+    OPENID_CLIENT_ID and OPENID_CLIENT_SECRET variables should be assigned
+    with correct values as registered in Keycloak.
 
-Similar to Keystone OS_CACERT variable can also be added to provide a certification for SSL/TLS
+Similar to Keystone OS_CACERT variable can also be added to provide a
+certification for SSL/TLS
 verification::
 
     $ export OS_CACERT=<path_to_ca_cert>
 
-In order to disable SSL/TLS certificate verification MISTRALCLIENT_INSECURE variable needs to be set
+In order to disable SSL/TLS certificate verification MISTRALCLIENT_INSECURE
+variable needs to be set
 to True::
 
     $ export MISTRALCLIENT_INSECURE=True
@@ -79,8 +87,8 @@ different from the one defined in the `mistral.conf` file in the
 `keystone_authtoken` section. (More detail in the :doc:`/configuration/index`).
 
 For example, if the mistral server is configured to authenticate with the
-`http://keystone1.example.com` cloud and the user wants to execute the workflow
+`http://keystone1.example.com` cloud and the user wants to execute the
-on the `http://keystone2.example.com` cloud.
+workflow on the `http://keystone2.example.com` cloud.
 
 The mistral.conf will look like::
 

doc/source/main_features.rst

@@ -7,7 +7,8 @@ Task result / Data flow
 
 Mistral supports transferring data from one task to another. In other words,
 if *taskA* produces a value then *taskB* which follows *taskA* can use it.
-In order to use this data Mistral relies on a query language called `YAQL <https://github.com/openstack/yaql>`_.
+In order to use this data Mistral relies on a query language called
+`YAQL <https://github.com/openstack/yaql>`_.
 YAQL is a powerful yet simple tool that allows the user to filter information,
 transform data and call functions. Find more information about it in the
 `YAQL official documentation <http://yaql.readthedocs.org>`_ . This mechanism
@@ -29,7 +30,8 @@ Workflow Language perspective:
 
    tasks:
      task1:
-       action: std.ssh host=<% $.host %> username=<% $.username %> password=<% $.password %>
+       action: std.ssh host=<% $.host %> username=<% $.username %> \
+               password=<% $.password %>
        input:
          cmd: "cd ~ && ls"
        on-complete: task2
@@ -206,9 +208,10 @@ tasks are complete.
 
 **Discriminator (join: one)**
 
-Discriminator is the special case of Partial Join where the *"join"* property has the value 1.
+Discriminator is the special case of Partial Join where the *"join"* property
-In this case instead of 1 it is possible to specify the special string value *"one"*
+has the value 1. In this case instead of 1 it is possible to specify the
-which is introduced for symmetry with *"all"*. However, it's up to the user whether to use *"1"* or *"one"*.
+special string value *"one"* which is introduced for symmetry with *"all"*.
+However, it's up to the user whether to use *"1"* or *"one"*.
 
 
 Processing collections (with-items)
@@ -233,7 +236,8 @@ YAML example
       tasks:
         create_servers:
           with-items: vm_name in <% $.vm_names %>
-          action: nova.servers_create name=<% $.vm_name %> image=<% $.image_ref %> flavor=<% $.flavor_ref %>
+          action: nova.servers_create name=<% $.vm_name %> \
+                  image=<% $.image_ref %> flavor=<% $.flavor_ref %>
           publish:
             vm_ids: <% $.create_servers.id %>
           on-success:
@@ -291,8 +295,8 @@ can be resolved by setting an expiration policy.
 This policy defines the maximum age of an execution since the last updated time
 (in minutes) and the maximum number of finished executions. Each evaluation will
 satisfy these conditions, so the expired executions (older than specified) will
-be deleted, and the number of execution in finished state (regardless of expiration)
+be deleted, and the number of execution in finished state (regardless of
-will be limited to max_finished_executions.
+expiration) will be limited to max_finished_executions.
 
 To enable the policy, edit the Mistral configuration file and specify
 ``evaluation_interval`` and at least one of the ``older_than``

doc/source/quickstart.rst

@@ -10,12 +10,14 @@ three prerequisites.
 Install and run Mistral
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Go through the installation manual: :doc:`Mistral Installation Guide <install/index>`
+Go through the installation manual:
+:doc:`Mistral Installation Guide <install/index>`
 
 Install Mistral client
 ~~~~~~~~~~~~~~~~~~~~~~
 
-To install mistralclient, please refer to :doc:`Mistral Client / CLI Guide <cli/index>`
+To install mistralclient, please refer to
+:doc:`Mistral Client / CLI Guide <cli/index>`
 
 Export Keystone credentials
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/terminology/executions.rst

@@ -53,9 +53,10 @@ least one *workflow execution*.
 Action execution
 ----------------
 
-Execution of specific action. To see details about actions, please refer to :ref:`actions-dsl`
+Execution of specific action. To see details about actions, please refer to
+:ref:`actions-dsl`
 
 Action execution has a state, input and output data.
 
-Usually action execution belongs to task execution but Mistral also is able to run
+Usually action execution belongs to task execution but Mistral also is able
-separate action executions.
+to run separate action executions.

tox.ini

@@ -57,7 +57,9 @@ commands = {posargs}
 [testenv:docs]
 basepython = python2.7
 setenv = PYTHONHASHSEED=0
-commands = python setup.py build_sphinx
+commands =
+  doc8 doc/source
+  python setup.py build_sphinx
 
 [testenv:releasenotes]
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
@@ -80,6 +82,11 @@ builtins = _
 enable-extensions = H106,H203
 exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,tools,scripts
 
+[doc8]
+extensions = .rst, .yaml
+# Maximal line length should be 80.
+max-line-length = 80
+
 [hacking]
 local-check-factory = mistral.hacking.checks.factory
 import_exceptions = mistral._i18n