From 9fb213c31518f201cfa548f6248da01b61ff0a07 Mon Sep 17 00:00:00 2001 From: Renat Akhmerov Date: Thu, 16 Jan 2020 19:09:36 +0700 Subject: [PATCH] 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 | 11 -- doc/source/_theme/layout.html | 4 - doc/source/_theme/theme.conf | 4 - doc/source/{ => admin}/architecture.rst | 1 + .../configuration/config-guide.rst | 0 .../{ => admin}/configuration/index.rst | 1 + .../configuration/policy-guide.rst | 0 .../configuration/samples/index.rst | 0 .../configuration/samples/policy-yaml.rst | 2 +- .../{ => admin}/img/mistral_architecture.png | Bin doc/source/admin/index.rst | 16 ++- .../{ => admin}/install/dashboard_guide.rst | 3 +- .../{ => admin}/install/get_started.rst | 6 +- doc/source/{ => admin}/install/index.rst | 13 +- .../{ => admin}/install/install-obs.rst | 0 .../{ => admin}/install/install-rdo.rst | 0 .../{ => admin}/install/install-ubuntu.rst | 21 +-- doc/source/{ => admin}/install/install.rst | 9 +- .../install/installation_guide.rst | 7 +- .../install/mistralclient_guide.rst | 84 +++++++---- doc/source/{ => admin}/install/next-steps.rst | 0 doc/source/{ => admin}/install/verify.rst | 0 doc/source/{ => admin}/quickstart.rst | 4 +- doc/source/api/index.rst | 7 - doc/source/conf.py | 81 ++++------- doc/source/contributor/index.rst | 13 -- .../contributor/coding_guidelines.rst | 7 +- .../{ => developer}/contributor/debug.rst | 0 .../{ => developer}/contributor/devstack.rst | 0 .../img/Pycharm_run_config_menu.png | Bin .../img/dashboard_debug_config.png} | Bin .../img/dashboard_django_settings.png} | Bin .../img/dashboard_environment_variables.png} | Bin doc/source/developer/contributor/index.rst | 11 ++ .../contributor/troubleshooting.rst | 16 ++- .../extensions}/creating_custom_action.rst | 0 .../extensions}/extending_yaql.rst | 0 doc/source/developer/extensions/index.rst | 9 ++ doc/source/developer/index.rst | 9 ++ doc/source/index.rst | 133 ++++++++---------- .../asynchronous_actions.rst | 0 doc/source/{ => user}/cli/index.rst | 0 doc/source/{ => user}/cookbooks.rst | 0 doc/source/user/index.rst | 26 ++++ doc/source/{ => user}/main_features.rst | 3 +- doc/source/{ => user}/overview.rst | 4 +- .../{api/v2.rst => user/rest_api_v2.rst} | 6 +- doc/source/{ => user}/terminology/actions.rst | 5 +- .../{ => user}/terminology/cron_triggers.rst | 0 .../{ => user}/terminology/executions.rst | 0 doc/source/{ => user}/terminology/index.rst | 1 + .../{ => user}/terminology/workbooks.rst | 0 .../{ => user}/terminology/workflows.rst | 0 doc/source/user/wf_lang_v2.rst | 4 +- 54 files changed, 270 insertions(+), 251 deletions(-) delete mode 100644 doc/source/_templates/sidebarlinks.html delete mode 100644 doc/source/_theme/layout.html delete mode 100644 doc/source/_theme/theme.conf rename doc/source/{ => admin}/architecture.rst (99%) rename doc/source/{ => admin}/configuration/config-guide.rst (100%) rename doc/source/{ => admin}/configuration/index.rst (85%) rename doc/source/{ => admin}/configuration/policy-guide.rst (100%) rename doc/source/{ => admin}/configuration/samples/index.rst (100%) rename doc/source/{ => admin}/configuration/samples/policy-yaml.rst (68%) rename doc/source/{ => admin}/img/mistral_architecture.png (100%) rename doc/source/{ => admin}/install/dashboard_guide.rst (95%) rename doc/source/{ => admin}/install/get_started.rst (93%) rename doc/source/{ => admin}/install/index.rst (71%) rename doc/source/{ => admin}/install/install-obs.rst (100%) rename doc/source/{ => admin}/install/install-rdo.rst (100%) rename doc/source/{ => admin}/install/install-ubuntu.rst (92%) rename doc/source/{ => admin}/install/install.rst (84%) rename doc/source/{ => admin}/install/installation_guide.rst (98%) rename doc/source/{ => admin}/install/mistralclient_guide.rst (79%) rename doc/source/{ => admin}/install/next-steps.rst (100%) rename doc/source/{ => admin}/install/verify.rst (100%) rename doc/source/{ => admin}/quickstart.rst (98%) delete mode 100644 doc/source/api/index.rst delete mode 100644 doc/source/contributor/index.rst rename doc/source/{ => developer}/contributor/coding_guidelines.rst (98%) rename doc/source/{ => developer}/contributor/debug.rst (100%) rename doc/source/{ => developer}/contributor/devstack.rst (100%) rename doc/source/{ => developer/contributor}/img/Pycharm_run_config_menu.png (100%) rename doc/source/{img/Mistral_dashboard_debug_config.png => developer/contributor/img/dashboard_debug_config.png} (100%) rename doc/source/{img/Mistral_dashboard_django_settings.png => developer/contributor/img/dashboard_django_settings.png} (100%) rename doc/source/{img/Mistral_dashboard_environment_variables.png => developer/contributor/img/dashboard_environment_variables.png} (100%) create mode 100644 doc/source/developer/contributor/index.rst rename doc/source/{ => developer}/contributor/troubleshooting.rst (85%) rename doc/source/{contributor => developer/extensions}/creating_custom_action.rst (100%) rename doc/source/{contributor => developer/extensions}/extending_yaql.rst (100%) create mode 100644 doc/source/developer/extensions/index.rst create mode 100644 doc/source/developer/index.rst rename doc/source/{contributor => user}/asynchronous_actions.rst (100%) rename doc/source/{ => user}/cli/index.rst (100%) rename doc/source/{ => user}/cookbooks.rst (100%) create mode 100644 doc/source/user/index.rst rename doc/source/{ => user}/main_features.rst (99%) rename doc/source/{ => user}/overview.rst (99%) rename doc/source/{api/v2.rst => user/rest_api_v2.rst} (99%) rename doc/source/{ => user}/terminology/actions.rst (91%) rename doc/source/{ => user}/terminology/cron_triggers.rst (100%) rename doc/source/{ => user}/terminology/executions.rst (100%) rename doc/source/{ => user}/terminology/index.rst (87%) rename doc/source/{ => user}/terminology/workbooks.rst (100%) rename doc/source/{ => user}/terminology/workflows.rst (100%) diff --git a/doc/source/_templates/sidebarlinks.html b/doc/source/_templates/sidebarlinks.html deleted file mode 100644 index bac67382f..000000000 --- a/doc/source/_templates/sidebarlinks.html +++ /dev/null @@ -1,11 +0,0 @@ -

Useful Links

- - -{% if READTHEDOCS %} - -{% endif %} \ No newline at end of file diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html deleted file mode 100644 index cd7ade1d7..000000000 --- a/doc/source/_theme/layout.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "basic/layout.html" %} -{% set css_files = css_files + ['_static/tweaks.css'] %} - -{% block relbar1 %}{% endblock relbar1 %} \ No newline at end of file diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf deleted file mode 100644 index 8c44b0ce4..000000000 --- a/doc/source/_theme/theme.conf +++ /dev/null @@ -1,4 +0,0 @@ -[theme] -inherit = nature -stylesheet = nature.css -pygments_style = tango \ No newline at end of file diff --git a/doc/source/architecture.rst b/doc/source/admin/architecture.rst similarity index 99% rename from doc/source/architecture.rst rename to doc/source/admin/architecture.rst index 72f3954e2..d88e13b2f 100644 --- a/doc/source/architecture.rst +++ b/doc/source/admin/architecture.rst @@ -1,3 +1,4 @@ +==================== Mistral Architecture ==================== diff --git a/doc/source/configuration/config-guide.rst b/doc/source/admin/configuration/config-guide.rst similarity index 100% rename from doc/source/configuration/config-guide.rst rename to doc/source/admin/configuration/config-guide.rst diff --git a/doc/source/configuration/index.rst b/doc/source/admin/configuration/index.rst similarity index 85% rename from doc/source/configuration/index.rst rename to doc/source/admin/configuration/index.rst index d6fcd8e59..1dffb7a6f 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/admin/configuration/index.rst @@ -1,3 +1,4 @@ +====================================== Mistral Configuration and Policy Guide ====================================== diff --git a/doc/source/configuration/policy-guide.rst b/doc/source/admin/configuration/policy-guide.rst similarity index 100% rename from doc/source/configuration/policy-guide.rst rename to doc/source/admin/configuration/policy-guide.rst diff --git a/doc/source/configuration/samples/index.rst b/doc/source/admin/configuration/samples/index.rst similarity index 100% rename from doc/source/configuration/samples/index.rst rename to doc/source/admin/configuration/samples/index.rst diff --git a/doc/source/configuration/samples/policy-yaml.rst b/doc/source/admin/configuration/samples/policy-yaml.rst similarity index 68% rename from doc/source/configuration/samples/policy-yaml.rst rename to doc/source/admin/configuration/samples/policy-yaml.rst index 7c93d3c21..063964249 100644 --- a/doc/source/configuration/samples/policy-yaml.rst +++ b/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 diff --git a/doc/source/img/mistral_architecture.png b/doc/source/admin/img/mistral_architecture.png similarity index 100% rename from doc/source/img/mistral_architecture.png rename to doc/source/admin/img/mistral_architecture.png diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 5b35740d3..b9a8ae3d1 100644 --- a/doc/source/admin/index.rst +++ b/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 diff --git a/doc/source/install/dashboard_guide.rst b/doc/source/admin/install/dashboard_guide.rst similarity index 95% rename from doc/source/install/dashboard_guide.rst rename to doc/source/admin/install/dashboard_guide.rst index 09fb6f3fa..f31d583c0 100644 --- a/doc/source/install/dashboard_guide.rst +++ b/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>` diff --git a/doc/source/install/get_started.rst b/doc/source/admin/install/get_started.rst similarity index 93% rename from doc/source/install/get_started.rst rename to doc/source/admin/install/get_started.rst index ad9326bc5..058dc238a 100644 --- a/doc/source/install/get_started.rst +++ b/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. diff --git a/doc/source/install/index.rst b/doc/source/admin/install/index.rst similarity index 71% rename from doc/source/install/index.rst rename to doc/source/admin/install/index.rst index a8ea283c5..a350a086d 100644 --- a/doc/source/install/index.rst +++ b/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 diff --git a/doc/source/install/install-obs.rst b/doc/source/admin/install/install-obs.rst similarity index 100% rename from doc/source/install/install-obs.rst rename to doc/source/admin/install/install-obs.rst diff --git a/doc/source/install/install-rdo.rst b/doc/source/admin/install/install-rdo.rst similarity index 100% rename from doc/source/install/install-rdo.rst rename to doc/source/admin/install/install-rdo.rst diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/admin/install/install-ubuntu.rst similarity index 92% rename from doc/source/install/install-ubuntu.rst rename to doc/source/admin/install/install-ubuntu.rst index 0d1007118..040693c32 100644 --- a/doc/source/install/install-ubuntu.rst +++ b/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 ` +:doc:`Mistral Devstack Installation ` 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 --------------------- diff --git a/doc/source/install/install.rst b/doc/source/admin/install/install.rst similarity index 84% rename from doc/source/install/install.rst rename to doc/source/admin/install/install.rst index ee4071614..7181c01a7 100644 --- a/doc/source/install/install.rst +++ b/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 diff --git a/doc/source/install/installation_guide.rst b/doc/source/admin/install/installation_guide.rst similarity index 98% rename from doc/source/install/installation_guide.rst rename to doc/source/admin/install/installation_guide.rst index dda967c03..0dc6aff1e 100644 --- a/doc/source/install/installation_guide.rst +++ b/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 ` +:doc:`Mistral Devstack Installation ` 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 ` +For details see :doc:`Mistral Configuration Guide ` **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 ` diff --git a/doc/source/install/mistralclient_guide.rst b/doc/source/admin/install/mistralclient_guide.rst similarity index 79% rename from doc/source/install/mistralclient_guide.rst rename to doc/source/admin/install/mistralclient_guide.rst index ead97315d..40c328420 100644 --- a/doc/source/install/mistralclient_guide.rst +++ b/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://:5000/v2.0 $ export OS_TENANT_NAME=tenant @@ -27,27 +34,36 @@ have auth variables:: $ export OS_MISTRAL_URL=http://: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= -.. 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://:/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= 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 \ diff --git a/doc/source/install/next-steps.rst b/doc/source/admin/install/next-steps.rst similarity index 100% rename from doc/source/install/next-steps.rst rename to doc/source/admin/install/next-steps.rst diff --git a/doc/source/install/verify.rst b/doc/source/admin/install/verify.rst similarity index 100% rename from doc/source/install/verify.rst rename to doc/source/admin/install/verify.rst diff --git a/doc/source/quickstart.rst b/doc/source/admin/quickstart.rst similarity index 98% rename from doc/source/quickstart.rst rename to doc/source/admin/quickstart.rst index 0a1ffa31c..36d5bf4b4 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/admin/quickstart.rst @@ -17,7 +17,7 @@ Mistral Client Command Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To use mistralclient, please refer to -:doc:`Mistral Client / CLI Guide ` +:doc:`Mistral Client / CLI Guide ` 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 ` +:doc:`Mistral Workflow Language specification ` Upload the workflow ------------------- diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst deleted file mode 100644 index 2c90de060..000000000 --- a/doc/source/api/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -REST API Specification -====================== - -.. toctree:: - :maxdepth: 2 - - v2 diff --git a/doc/source/conf.py b/doc/source/conf.py index 7c5aa41c4..5a7b51271 100644 --- a/doc/source/conf.py +++ b/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 # " v 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': '', diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst deleted file mode 100644 index b2548a1ab..000000000 --- a/doc/source/contributor/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -Developer's Reference -===================== - -.. toctree:: - :maxdepth: 3 - - coding_guidelines - creating_custom_action - extending_yaql - asynchronous_actions - devstack - debug - troubleshooting diff --git a/doc/source/contributor/coding_guidelines.rst b/doc/source/developer/contributor/coding_guidelines.rst similarity index 98% rename from doc/source/contributor/coding_guidelines.rst rename to doc/source/developer/contributor/coding_guidelines.rst index af969f035..48d4438b7 100644 --- a/doc/source/contributor/coding_guidelines.rst +++ b/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 diff --git a/doc/source/contributor/debug.rst b/doc/source/developer/contributor/debug.rst similarity index 100% rename from doc/source/contributor/debug.rst rename to doc/source/developer/contributor/debug.rst diff --git a/doc/source/contributor/devstack.rst b/doc/source/developer/contributor/devstack.rst similarity index 100% rename from doc/source/contributor/devstack.rst rename to doc/source/developer/contributor/devstack.rst diff --git a/doc/source/img/Pycharm_run_config_menu.png b/doc/source/developer/contributor/img/Pycharm_run_config_menu.png similarity index 100% rename from doc/source/img/Pycharm_run_config_menu.png rename to doc/source/developer/contributor/img/Pycharm_run_config_menu.png diff --git a/doc/source/img/Mistral_dashboard_debug_config.png b/doc/source/developer/contributor/img/dashboard_debug_config.png similarity index 100% rename from doc/source/img/Mistral_dashboard_debug_config.png rename to doc/source/developer/contributor/img/dashboard_debug_config.png diff --git a/doc/source/img/Mistral_dashboard_django_settings.png b/doc/source/developer/contributor/img/dashboard_django_settings.png similarity index 100% rename from doc/source/img/Mistral_dashboard_django_settings.png rename to doc/source/developer/contributor/img/dashboard_django_settings.png diff --git a/doc/source/img/Mistral_dashboard_environment_variables.png b/doc/source/developer/contributor/img/dashboard_environment_variables.png similarity index 100% rename from doc/source/img/Mistral_dashboard_environment_variables.png rename to doc/source/developer/contributor/img/dashboard_environment_variables.png diff --git a/doc/source/developer/contributor/index.rst b/doc/source/developer/contributor/index.rst new file mode 100644 index 000000000..00a3a286e --- /dev/null +++ b/doc/source/developer/contributor/index.rst @@ -0,0 +1,11 @@ +========================= +Contributor Documentation +========================= + +.. toctree:: + :maxdepth: 3 + + coding_guidelines + debug + troubleshooting + devstack diff --git a/doc/source/contributor/troubleshooting.rst b/doc/source/developer/contributor/troubleshooting.rst similarity index 85% rename from doc/source/contributor/troubleshooting.rst rename to doc/source/developer/contributor/troubleshooting.rst index 7f55ca270..bf9356cdb 100644 --- a/doc/source/contributor/troubleshooting.rst +++ b/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. diff --git a/doc/source/contributor/creating_custom_action.rst b/doc/source/developer/extensions/creating_custom_action.rst similarity index 100% rename from doc/source/contributor/creating_custom_action.rst rename to doc/source/developer/extensions/creating_custom_action.rst diff --git a/doc/source/contributor/extending_yaql.rst b/doc/source/developer/extensions/extending_yaql.rst similarity index 100% rename from doc/source/contributor/extending_yaql.rst rename to doc/source/developer/extensions/extending_yaql.rst diff --git a/doc/source/developer/extensions/index.rst b/doc/source/developer/extensions/index.rst new file mode 100644 index 000000000..200a7ccb9 --- /dev/null +++ b/doc/source/developer/extensions/index.rst @@ -0,0 +1,9 @@ +========================== +Writing Mistral Extensions +========================== + +.. toctree:: + :maxdepth: 3 + + creating_custom_action + extending_yaql diff --git a/doc/source/developer/index.rst b/doc/source/developer/index.rst new file mode 100644 index 000000000..0830cbcfe --- /dev/null +++ b/doc/source/developer/index.rst @@ -0,0 +1,9 @@ +======================= +Developer Documentation +======================= + +.. toctree:: + :maxdepth: 2 + + contributor/index + extensions/index diff --git a/doc/source/index.rst b/doc/source/index.rst index 22eb23713..06f49384a 100644 --- a/doc/source/index.rst +++ b/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 `_ 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 `_: 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 the contents of this document. diff --git a/doc/source/contributor/asynchronous_actions.rst b/doc/source/user/asynchronous_actions.rst similarity index 100% rename from doc/source/contributor/asynchronous_actions.rst rename to doc/source/user/asynchronous_actions.rst diff --git a/doc/source/cli/index.rst b/doc/source/user/cli/index.rst similarity index 100% rename from doc/source/cli/index.rst rename to doc/source/user/cli/index.rst diff --git a/doc/source/cookbooks.rst b/doc/source/user/cookbooks.rst similarity index 100% rename from doc/source/cookbooks.rst rename to doc/source/user/cookbooks.rst diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 000000000..7f0231d32 --- /dev/null +++ b/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 diff --git a/doc/source/main_features.rst b/doc/source/user/main_features.rst similarity index 99% rename from doc/source/main_features.rst rename to doc/source/user/main_features.rst index edc1b7422..7f040e5bc 100644 --- a/doc/source/main_features.rst +++ b/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 ` +See more at :doc:`Workflow namespaces ` diff --git a/doc/source/overview.rst b/doc/source/user/overview.rst similarity index 99% rename from doc/source/overview.rst rename to doc/source/user/overview.rst index 0f95d269c..23c51c3b2 100644 --- a/doc/source/overview.rst +++ b/doc/source/user/overview.rst @@ -1,5 +1,5 @@ -Mistral Overview -================ +Quick Overview +============== What is Mistral? ---------------- diff --git a/doc/source/api/v2.rst b/doc/source/user/rest_api_v2.rst similarity index 99% rename from doc/source/api/v2.rst rename to doc/source/user/rest_api_v2.rst index 237629bf9..37dedeb47 100644 --- a/doc/source/api/v2.rst +++ b/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 ^^^^^^^^^^^ diff --git a/doc/source/terminology/actions.rst b/doc/source/user/terminology/actions.rst similarity index 91% rename from doc/source/terminology/actions.rst rename to doc/source/user/terminology/actions.rst index e0283a6e3..1de1dce63 100644 --- a/doc/source/terminology/actions.rst +++ b/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 ` +:doc:`How to work with 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 ` +:doc:`How to write an Action Plugin +` Ad-hoc actions diff --git a/doc/source/terminology/cron_triggers.rst b/doc/source/user/terminology/cron_triggers.rst similarity index 100% rename from doc/source/terminology/cron_triggers.rst rename to doc/source/user/terminology/cron_triggers.rst diff --git a/doc/source/terminology/executions.rst b/doc/source/user/terminology/executions.rst similarity index 100% rename from doc/source/terminology/executions.rst rename to doc/source/user/terminology/executions.rst diff --git a/doc/source/terminology/index.rst b/doc/source/user/terminology/index.rst similarity index 87% rename from doc/source/terminology/index.rst rename to doc/source/user/terminology/index.rst index 109bc6e00..de01f80e6 100644 --- a/doc/source/terminology/index.rst +++ b/doc/source/user/terminology/index.rst @@ -1,3 +1,4 @@ +=================== Mistral Terminology =================== diff --git a/doc/source/terminology/workbooks.rst b/doc/source/user/terminology/workbooks.rst similarity index 100% rename from doc/source/terminology/workbooks.rst rename to doc/source/user/terminology/workbooks.rst diff --git a/doc/source/terminology/workflows.rst b/doc/source/user/terminology/workflows.rst similarity index 100% rename from doc/source/terminology/workflows.rst rename to doc/source/user/terminology/workflows.rst diff --git a/doc/source/user/wf_lang_v2.rst b/doc/source/user/wf_lang_v2.rst index da1681552..a240d8fc0 100644 --- a/doc/source/user/wf_lang_v2.rst +++ b/doc/source/user/wf_lang_v2.rst @@ -1,5 +1,5 @@ -Mistral Workflow Language v2 specification -========================================== +Mistral Workflow Language (v2) +============================== Introduction ------------