The first iteration of restructuring Mistral doc

* Grouped documentation articles into several main parts: user docs,
  admin docs, developer docs.
* Changed the index page so that it contains links to the index pages
  of the main documentation parts like user docs, admin docs etc.
* Fixed all the broken links
* Removed index generation since it's not informative at all in its
  current form and it exposes code internals (REST controller class
  names)
* Removed obsolete properties that are no longer used by the
  "openstackdocstheme" project
* Removed obsolete static html files
* Moved part of the images to the folders where they are used

Further work:

* Refactor main chapters (user, admin, developer) one by one and
  make them look consistent. For example, there are several pages
  that provide similar kind of information: overview, quick start,
  main features etc. It is a mess that's been accumulated throughout
  the last 4-5 years.
* Fill the gaps. Add all missing pages like: event notifications,
  workflow environment, etc.
* Move cookbooks from Wiki to this doc.

Partially implements: blueprint mistral-restructure-docs
Change-Id: Ia722a6885ad2fb97d63a34285b0a5b1a23da79e8

doc/source/_templates/sidebarlinks.html

@@ -1,11 +0,0 @@
-<h3>Useful Links</h3>
-<ul>
-  <li><a href="https://launchpad.net/mistral">Mistral @ Launchpad</a></li>
-  <li><a href="https://wiki.openstack.org/wiki/mistral">Mistral @ OpenStack Wiki</a></li>
-</ul>
-
-{% if READTHEDOCS %}
-<script type='text/javascript'>
-    $('div.body').css('margin', 0)
-</script>
-{% endif %}

doc/source/_theme/layout.html

@@ -1,4 +0,0 @@
-{% extends "basic/layout.html" %}
-{% set css_files = css_files + ['_static/tweaks.css'] %}
-
-{% block relbar1 %}{% endblock relbar1 %}

doc/source/_theme/theme.conf

@@ -1,4 +0,0 @@
-[theme]
-inherit = nature
-stylesheet = nature.css
-pygments_style = tango

doc/source/admin/architecture.rst

@@ -1,3 +1,4 @@
+====================
 Mistral Architecture
 ====================
 

doc/source/admin/configuration/index.rst

@@ -1,3 +1,4 @@
+======================================
 Mistral Configuration and Policy Guide
 ======================================
 

doc/source/admin/configuration/samples/policy-yaml.rst

@@ -5,5 +5,5 @@ policy.yaml
 Use the ``policy.yaml`` file to define additional access controls that apply to
 the Mistral services:
 
-.. literalinclude:: ../../_static/mistral.policy.yaml.sample
+.. literalinclude:: ../../../_static/mistral.policy.yaml.sample
 

doc/source/admin/index.rst

@@ -1,7 +1,15 @@
-Mistral Admin Guide
-=====================
+===========================
+Administrator Documentation
+===========================
+
+This chapter contains all needed information about how to install and
+configure a Mistral cluster.
 
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 1
 
-   upgrade_guide
+    architecture
+    quickstart
+    install/index
+    configuration/index
+    upgrade_guide

doc/source/admin/install/dashboard_guide.rst

@@ -61,4 +61,5 @@ The following should get you started:
 
 Debug instructions
 ------------------
-Please refer to :doc:`Mistral Troubleshooting <../contributor/troubleshooting>`
+Please refer to :doc:`Mistral Troubleshooting
+<../../developer/contributor/troubleshooting>`

doc/source/admin/install/get_started.rst

@@ -1,6 +1,6 @@
-=================================
-Workflow service overview
-=================================
+=========================
+Workflow Service Overview
+=========================
 
 Mistral is a workflow service that enables setting up and scheduling tasks and
 task relations that have to be executed in a particular order, called workflows.

doc/source/admin/install/index.rst

@@ -1,19 +1,20 @@
+==========================
 Mistral Installation Guide
 ==========================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   get_started.rst
-   install.rst
-   verify.rst
-   next-steps.rst
+   get_started
+   install
+   verify
+   next-steps
    dashboard_guide
    installation_guide
    mistralclient_guide
 
 The Workflow service (mistral) enables setting up task relations that have to be
- executed in a particular order, called workflows.
+executed in a particular order, called workflows.
 
 This chapter assumes a working setup of OpenStack following the
 `OpenStack Installation Tutorial

doc/source/admin/install/install-ubuntu.rst

@@ -1,13 +1,12 @@
 .. _install-ubuntu:
 
-Install and configure for Ubuntu
+================================
+Install and Configure for Ubuntu
 ================================
 
 This section describes how to install and configure the Workflow Service
 service for Ubuntu.
 
-
-
 Prerequisites
 -------------
 
@@ -20,13 +19,11 @@ Prerequisites
       # apt-get install python-setuptools python-pip libffi-dev libxslt1-dev \
         libxml2-dev libyaml-dev libssl-dev python3-dev tox mistral-common
 
-
-
 Installation
 ------------
 
 **NOTE**: For instructions on how to install Mistral using devstack, refer to
-:doc:`Mistral Devstack Installation </contributor/devstack>`
+:doc:`Mistral Devstack Installation </developer/contributor/devstack>`
 
 Clone the repo and go to the repo directory:
 
@@ -86,11 +83,14 @@ or the EasyInstall tool, however, it does not actually install anything.
 Instead, it creates a special .egg-link file in the deployment directory that
 links to your project’s source code.
 
+Configuring Mistral
+-------------------
 
-.. include:: ../configuration/index.rst
+Refer :doc:`../configuration/index` to find general information on how to
+configure Mistral server.
 
 
-Before the first run
+Before The First Run
 --------------------
 
 After the installation, you will see the **mistral-server** and
@@ -196,8 +196,11 @@ get delivered if the Mistral servers are launched on different processes
 because the "fake" transport is using an in-process queue.
 
 
-.. include:: mistralclient_guide.rst
+Mistral Client Installation
+---------------------------
 
+Refer :doc:`/admin/install/mistralclient_guide` to find out how to install
+Mistral Client.
 
 Finalize installation
 ---------------------

doc/source/admin/install/install.rst

@@ -1,7 +1,8 @@
 .. _install:
 
+=====================
 Install and configure
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 This section describes how to install and configure the
 Workflow Service, code-named mistral, on the controller node.
@@ -19,6 +20,6 @@ Note that installation and configuration vary by distribution.
 .. toctree::
    :maxdepth: 2
 
-   install-ubuntu.rst
-   install-rdo.rst
-   install-obs.rst
+   install-ubuntu
+   install-rdo
+   install-obs

doc/source/admin/install/installation_guide.rst

@@ -1,3 +1,4 @@
+==========================
 Mistral Installation Guide
 ==========================
 
@@ -32,7 +33,7 @@ Installation
 ------------
 
 **NOTE**: If it is needed to install Mistral using devstack, please refer to
-:doc:`Mistral Devstack Installation </contributor/devstack>`
+:doc:`Mistral Devstack Installation </developer/contributor/devstack>`
 
 First of all, clone the repo and go to the repo directory::
 
@@ -50,7 +51,7 @@ Generate config::
 Configure Mistral as needed. The configuration file is located in
 ``etc/mistral.conf.sample``. You will need to modify the configuration options
 and then copy it into ``/etc/mistral/mistral.conf``.
-For details see :doc:`Mistral Configuration Guide </configuration/index>`
+For details see :doc:`Mistral Configuration Guide </admin/configuration/index>`
 
 **Virtualenv installation**::
 
@@ -452,4 +453,4 @@ execute mistral commands.
 Mistral Client Installation
 ---------------------------
 
-Please refer to :doc:`Mistral Client / CLI Guide <../cli/index>`
+Please refer to :doc:`Mistral Client / CLI Guide </user/cli/index>`

doc/source/admin/install/mistralclient_guide.rst

@@ -1,24 +1,31 @@
-Mistral Client Installation Guide
----------------------------------
+===========================
+Mistral Client Installation
+===========================
 
 To install ``python-mistralclient``, it is required to have ``pip``
-(in most cases). Make sure that ``pip`` is installed. Then type::
+(in most cases). Make sure that ``pip`` is installed. Then type:
+
+.. code-block:: console
 
     $ pip install python-mistralclient
 
 Or, if it is needed to install ``python-mistralclient`` from master branch,
-type::
+type:
+
+.. code-block:: console
 
     $ pip install git+https://github.com/openstack/python-mistralclient.git
 
 After ``python-mistralclient`` is installed you will see command ``mistral``
 in your environment.
 
-Configure authentication against Keystone
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configure Authentication Against Keystone
+-----------------------------------------
 
 If Keystone is used for authentication in Mistral, then the environment should
-have auth variables::
+have auth variables:
+
+.. code-block:: console
 
     $ export OS_AUTH_URL=http://<Keystone_host>:5000/v2.0
     $ export OS_TENANT_NAME=tenant
@@ -27,27 +34,36 @@ have auth variables::
     $ 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::
+and in the case when you are authenticating against keystone over https:
+
+.. code-block:: console
 
     $ 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::
+You can see the list of available commands by typing:
+
+.. code-block:: console
 
     $ mistral --help
 
-To make sure Mistral client works, type::
+To make sure Mistral client works, type:
+
+.. code-block:: console
 
     $ mistral workbook-list
 
-Configure authentication against Keycloak
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configure Authentication Against Keycloak
+-----------------------------------------
 
 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::
+In order to use it on the client side the environment should look as follows:
+
+.. code-block:: console
 
     $ export MISTRAL_AUTH_TYPE=keycloak-oidc
     $ export OS_AUTH_URL=https://<Keycloak-server-host>:<Keycloak-server-port>/auth
@@ -69,34 +85,43 @@ In order to use it on the client side the environment should look as follows::
 
 Similar to Keystone OS_CACERT variable can also be added to provide a
 certification for SSL/TLS
-verification::
+verification:
+
+.. code-block:: console
 
     $ export OS_CACERT=<path_to_ca_cert>
 
 In order to disable SSL/TLS certificate verification MISTRALCLIENT_INSECURE
 variable needs to be set
-to True::
+to True:
+
+.. code-block:: console
 
     $ export MISTRALCLIENT_INSECURE=True
 
-Targeting non-preconfigured clouds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-
+Targeting Non-preconfigured Clouds
+----------------------------------
 
 Mistral is capable of executing workflows on external OpenStack clouds,
 different from the one defined in the `mistral.conf` file in the
-`keystone_authtoken` section. (More detail in the :doc:`/configuration/index`).
+`keystone_authtoken` section. (More detail in the
+:doc:`/admin/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 on the `http://keystone2.example.com` cloud.
 
-The mistral.conf will look like::
+The mistral.conf will look like:
+
+.. code-block:: console
 
     [keystone_authtoken]
     www_authenticate_uri = http://keystone1.example.com:5000/v3
     ...
 
-The client side parameters will be::
+The client side parameters will be:
+
+.. code-block:: console
 
     $ export OS_AUTH_URL=http://keystone1.example.com:5000/v3
     $ export OS_USERNAME=mistral_user
@@ -105,16 +130,17 @@ The client side parameters will be::
     $ export OS_TARGET_USERNAME=cloud_user
     ...
 
-.. note:: Every `OS_*` parameter has an `OS_TARGET_*` correspondent. For more
-          detail, check out `mistral --help`
+.. note::
+    Every `OS_*` parameter has an `OS_TARGET_*` correspondent. For more
+    detail, check out `mistral --help`
 
 The `OS_*` parameters are used to authenticate and authorize the user with
 Mistral, that is, to check if the user is allowed to utilize the Mistral
 service. Whereas the `OS_TARGET_*` parameters are used to define the user that
-executes the workflow on the external cloud, keystone2.example.com/.
+executes the workflow on the external cloud, keystone2.example.com.
 
 Use cases
-"""""""""
+^^^^^^^^^
 
 **Authenticate in Mistral and execute OpenStack actions with different users**
 
@@ -126,7 +152,7 @@ cloud.
 As a user of Mistral, I want to execute a workflow on a cloud of my choice.
 
 Special cases
-"""""""""""""
+^^^^^^^^^^^^^
 
 **Using Mistral with zero OpenStack configuration**:
 
@@ -138,7 +164,9 @@ If authentication is turned off in the Mistral server (Pecan's
 OpenStack cloud even when it isn't deployed in an OpenStack environment (i.e.
 no Keystone integration).
 
-With this setup, the following call will return the heat stack list::
+With this setup, the following call will return the heat stack list:
+
+.. code-block:: console
 
     $ mistral \
         --os-target-auth-url=http://keystone2.example.com:5000/v3 \

doc/source/admin/quickstart.rst

@@ -17,7 +17,7 @@ Mistral Client Command Guide
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To use mistralclient, please refer to
-:doc:`Mistral Client / CLI Guide <cli/index>`
+:doc:`Mistral Client / CLI Guide </user/cli/index>`
 
 Export Keystone credentials
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -64,7 +64,7 @@ This simple workflow iterates through a list of names in ``task1`` (using
 then stores the word "Done" as a result of the second task (`task2`).
 
 To learn more about the Mistral Workflows and what you can do, read the
-:doc:`Mistral Workflow Language specification <user/wf_lang_v2>`
+:doc:`Mistral Workflow Language specification </user/wf_lang_v2>`
 
 Upload the workflow
 -------------------

doc/source/api/index.rst

@@ -1,7 +0,0 @@
-REST API Specification
-======================
-
-.. toctree::
-   :maxdepth: 2
-
-   v2

doc/source/conf.py

@@ -1,15 +1,20 @@
-# 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
+# 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
+#   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.
+# 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.
+#
+#  Mistral documentation build configuration file
+#
+# Refer to the Sphinx documentation for advice on configuring this file:
+#
+#   http://www.sphinx-doc.org/en/stable/config.html
 
 import os
 import sys
@@ -19,13 +24,16 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
+
 sys.path.insert(0, os.path.abspath('../../'))
 sys.path.insert(0, os.path.abspath('../'))
 sys.path.insert(0, os.path.abspath('./'))
+
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinxcontrib.pecanwsme.rest',
@@ -40,34 +48,20 @@ wsme_protocols = ['restjson']
 
 suppress_warnings = ['app.add_directive']
 
-# Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
-
-# autodoc generation is a bit aggressive and a nuisance when doing heavy
-# text edit cycles.
-# execute "export SPHINX_DEBUG=1" in your terminal to disable
-
-# The suffix of source filenames.
+# The suffix of source file names.
 source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'Mistral'
-copyright = u'2014, Mistral Contributors'
+project = 'Mistral'
+copyright = u'2020, Mistral Contributors'
 
 policy_generator_config_file = \
     '../../tools/config/policy-generator.mistral.conf'
 sample_policy_basename = '_static/mistral'
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-from mistral.version import version_info
-release = version_info.release_string()
-version = version_info.version_string()
-
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 show_authors = False
@@ -90,34 +84,13 @@ pygments_style = 'sphinx'
 
 html_theme = 'openstackdocs'
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
-
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['mistral.']
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-# Must set this variable to include year, month, day, hours, and minutes.
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
-
 # The name for this set of Sphinx documents. If None, it defaults to
 # "<project> v<release> documentation".
 html_title = 'Mistral'
 
-# Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-    'index': [
-        'sidebarlinks.html', 'localtoc.html', 'searchbox.html',
-        'sourcelink.html'
-    ],
-    '**': [
-        'localtoc.html', 'relations.html',
-        'searchbox.html', 'sourcelink.html'
-    ]
-}
-
 # -- Options for manual page output -------------------------------------------
 
 # One entry per manual page. List of tuples
@@ -131,19 +104,19 @@ man_pages = [
 man_show_urls = True
 
 # -- Options for openstackdocstheme -------------------------------------------
+
 repository_name = 'openstack/mistral'
 bug_project = 'mistral'
-bug_tag = ''
+bug_tag = 'doc'
 
 latex_use_xindy = False
 
-# -- Options for LaTeX output ------------------------------------------------
+html_theme_options = {
+    "display_global_toc_section": True,
+    "sidebar_mode": "toctree",
+}
 
-latex_documents = [
-    ('index', 'doc-mistral.tex',
-     u'Mistral Documentation',
-     u'OpenStack','manual', True),
-]
+# -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
     'makeindex': '',

doc/source/contributor/index.rst

@@ -1,13 +0,0 @@
-Developer's Reference
-=====================
-
-.. toctree::
-   :maxdepth: 3
-
-   coding_guidelines
-   creating_custom_action
-   extending_yaql
-   asynchronous_actions
-   devstack
-   debug
-   troubleshooting

doc/source/developer/contributor/coding_guidelines.rst

@@ -36,7 +36,7 @@ The guidelines are based on the three main values:
 - **Communication.** When writing code we always try to create it in a way
   that it's easy to read and understand. This is important because most of
   the time developers spend on reading existing code, not writing new.
-- **Simplicity.** It makes sense to write code that use minimal means that
+- **Simplicity.** It makes sense to write code that uses minimal means that
   solves a task at hand.
 - **Flexibility.** In most cases it's better to keep options open because
   in programming there's no such thing as "done". Pretty much all code gets
@@ -164,9 +164,8 @@ Problematic Code
         return result
 
 Is this method easy to understand? Well, if this code is part of a small
-program (e.g. a 200-300 lines script) is small then it may be ok. But when
-it's a system with dozens of thousands lines of code then it has a number of
-issues.
+program (e.g. a 200-300 lines script) then it may be ok. But when it's a
+system with dozens of thousands lines of code then it has a number of issues.
 
 The most important issue is that we don't know the type of the "task" method
 argument. In order to find it we'll have to see where this method is called

doc/source/developer/contributor/index.rst

@@ -0,0 +1,11 @@
+=========================
+Contributor Documentation
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+   coding_guidelines
+   debug
+   troubleshooting
+   devstack

doc/source/developer/contributor/troubleshooting.rst

@@ -1,13 +1,15 @@
+=============================
 Troubleshooting And Debugging
 =============================
 
 Mistral-Dashboard debug instructions
-------------------------------------
+====================================
 
 **Pycharm**
 
-Debugging OpenStack Mistral-Dashboard is the same
-as debugging OpenStack Horizon.
+Debugging OpenStack Mistral-Dashboard is the same as debugging OpenStack
+Horizon.
+
 The following instructions should get you sorted to debug both on the same run.
 
 Set PyCharm debug settings:
@@ -21,12 +23,12 @@ Enter the following:
   d. Manage script: manage.py (also in your horizon folder)
   e. Click OK
 
-.. image:: ../img/Mistral_dashboard_django_settings.png
+.. image:: img/dashboard_django_settings.png
 
 2. Enter debug configurations menu, using the tiny arrow pointing down,
    left to the "play" icon, or under the run menu
 
-.. image:: ../img/Pycharm_run_config_menu.png
+.. image:: img/Pycharm_run_config_menu.png
 
 3. In the new window, click the green plus icon and then select "Django server"
    to create a new Django Server configuration.
@@ -36,7 +38,7 @@ Enter the following:
   a. Name that configuration Horizon
   b. Enter some port so it won't run on the default (for example - port: 4000)
 
-.. image:: ../img/Mistral_dashboard_debug_config.png
+.. image:: img/dashboard_debug_config.png
 
 5. Click on Environment variables button, then in the new window:
 
@@ -44,7 +46,7 @@ Enter the following:
   b. Create a new pair - DJANGO_SETTINGS_MODULE : openstack_dashboard.settings
   c. When finished click OK.
 
-.. image:: ../img/Mistral_dashboard_environment_variables.png
+.. image:: img/dashboard_environment_variables.png
 
 
 You should now be able to debug and run the project using PyCharm.

doc/source/developer/extensions/index.rst

@@ -0,0 +1,9 @@
+==========================
+Writing Mistral Extensions
+==========================
+
+.. toctree::
+   :maxdepth: 3
+
+   creating_custom_action
+   extending_yaql

doc/source/developer/index.rst

@@ -0,0 +1,9 @@
+=======================
+Developer Documentation
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   contributor/index
+   extensions/index

doc/source/index.rst

@@ -1,85 +1,68 @@
-Welcome to the Mistral documentation!
-=====================================
+========================
+Mistral Workflow Service
+========================
 
-Mistral is the OpenStack workflow service. This project aims to provide
-a mechanism to define tasks and workflows without writing code, manage
-and execute them in the cloud environment.
+What is Mistral?
+================
 
-A workflow visualization tool is available via
-`CloudFlow <https://github.com/nokia/CloudFlow>`_ and will help you debug
-workflow executions, identify execution paths, explore task run times,
-easily access input/output values and so many more...
+Mistral is a workflow service project. It aims to provide a mechanism
+to define complex graphs of tasks (workflows) in a simple YAML-based
+language and manage and run them in a scalable and reliable manner.
 
-Overview
---------
+Quick Overview
+==============
+
+* :doc:`user/overview`: If you've just started with Mistral, this short
+  article will help you understand the main Mistral ideas and concepts.
+
+For End Users
+=============
+
+* :doc:`user/index`: If you're going to use Mistral functionality as an
+  end user, i.e. writing and running workflows, then you need to read
+  the full user documentation that tells about all Mistral features,
+  including the full description of the Mistral Workflow Language and
+  Mistral ReST API.
+* :doc:`user/wf_lang_v2`: If you just want a direct link to the full
+  specification of the Mistral Workflow Language, this is it.
+* :doc:`user/rest_api_v2`: This is where you can find the full specification
+  of the Mistral REST API.
+
+For Administrators and Operators
+================================
+
+* :doc:`admin/index`: If you need to install, configure and maintain a
+  Mistral cluster, this is a place to start.
+
+For Developers
+==============
+
+* :doc:`developer/index`: If you want to contribute to the project or
+  write Mistral extensions, please start here.
+* :doc:`developer/extensions/index`: Read this section if you want to write
+  custom Mistral actions and other extensions.
+
+Workflow Visualization (CloudFlow)
+==================================
+
+* `CloudFlow <https://github.com/nokia/CloudFlow>`_: If you're looking for
+  a nice workflow visualization tool then visit this web page. CloudFlow
+  provides a nice UI for debugging and analysing workflow executions.
+
+Main Chapters
+=============
 
 .. toctree::
     :maxdepth: 1
+    :includehidden:
 
-    overview
-    quickstart
-    architecture
-    terminology/index
-    main_features
-    cookbooks
+    user/index
+    admin/index
+    developer/index
 
-User guide
-----------
+.. only:: html
 
-**Installation**
+Search
+======
 
-.. toctree::
-   :maxdepth: 2
-
-   install/index
-   configuration/index
-
-**Mistral features**
-
-.. toctree::
-   :maxdepth: 1
-
-   user/wf_namespaces
-
-**API**
-
-.. toctree::
-   :maxdepth: 2
-
-   api/index
-
-**Mistral Workflow Language**
-
-.. toctree::
-   :maxdepth: 2
-
-   user/wf_lang_v2
-
-**CLI**
-
-.. toctree::
-   :maxdepth: 1
-
-   cli/index
-
-Developer guide
----------------
-
-.. toctree::
-   :maxdepth: 2
-
-   contributor/index
-
-Admin guide
------------
-
-.. toctree::
-   :maxdepth: 2
-
-   admin/index
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
+* :ref:`Document search <search>`: Search the contents of this document.

doc/source/user/index.rst

@@ -0,0 +1,26 @@
+==================
+User Documentation
+==================
+
+This part of the documentation provides detailed information about the
+Mistral capabilities, use cases and also complete description of Mistral
+Workflow Language and APIs. If you want to write Mistral workflows and
+and run them with the Mistral service, it is highly recommended to read
+the articles of this part one by one. Please pay a special attention to
+the examples since they're proven to explain Mistral concepts best.
+However, you can also read individual articles in case you are searching
+info on concrete features.
+
+
+.. toctree::
+    :maxdepth: 2
+
+    overview
+    terminology/index
+    main_features
+    wf_namespaces
+    asynchronous_actions
+    wf_lang_v2
+    rest_api_v2
+    cli/index
+    cookbooks

doc/source/user/main_features.rst

@@ -1,3 +1,4 @@
+=====================
 Mistral Main Features
 =====================
 
@@ -348,4 +349,4 @@ Mistral allows creating workflows within a namespace. So it is possible to
 create many workflows with the same name as long as they are in different
 namespaces.
 
-See more at :doc:`Workflow namespaces <user/wf_namespaces>`
+See more at :doc:`Workflow namespaces </user/wf_namespaces>`

doc/source/user/overview.rst

@@ -1,5 +1,5 @@
-Mistral Overview
-================
+Quick Overview
+==============
 
 What is Mistral?
 ----------------

doc/source/user/rest_api_v2.rst

@@ -1,14 +1,12 @@
-V2 API
-======
+REST API V2
+===========
 
 This API describes the ways of interacting with Mistral service via
 HTTP protocol using Representational State Transfer concept (ReST).
 
-
 Basics
 -------
 
-
 Media types
 ^^^^^^^^^^^
 

doc/source/user/terminology/actions.rst

@@ -19,7 +19,7 @@ its state and result.
 
 .. image:: /img/Mistral_actions.png
 
-:doc:`How to work with asynchronous actions </contributor/asynchronous_actions>`
+:doc:`How to work with asynchronous actions </user/asynchronous_actions>`
 
 System actions
 --------------
@@ -27,7 +27,8 @@ System actions
 System actions are provided by Mistral out of the box and are available to all
 users. Additional actions can be added via the custom action plugin mechanism.
 
-:doc:`How to write an Action Plugin </contributor/creating_custom_action>`
+:doc:`How to write an Action Plugin
+</developer/extensions/creating_custom_action>`
 
 
 Ad-hoc actions

doc/source/user/terminology/index.rst

@@ -1,3 +1,4 @@
+===================
 Mistral Terminology
 ===================
 

doc/source/user/wf_lang_v2.rst

@@ -1,5 +1,5 @@
-Mistral Workflow Language v2 specification
-==========================================
+Mistral Workflow Language (v2)
+==============================
 
 Introduction
 ------------