Refactor mistral documentation

* renaming developer doc to contributor doc
* flattening contributor doc to ease reading the whole content in a shot
* rewrite devstack documentation
* adding Axel and myself as maintainers

Signed-off-by: Arnaud Morin <arnaud.morin@ovhcloud.com>
Change-Id: If25d342c7cc2568b2d86c88bf6a049522559bf50

doc/source/admin/install/dashboard_guide.rst

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

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

@@ -23,7 +23,7 @@ Installation
 ------------
 
 **NOTE**: For instructions on how to install Mistral using devstack, refer to
-:doc:`Mistral Devstack Installation </developer/contributor/devstack>`
+:doc:`Mistral Devstack Installation <../../contributor/devstack>`
 
 Clone the repo and go to the repo directory:
 

doc/source/admin/install/installation_guide.rst

@@ -33,7 +33,7 @@ Installation
 ------------
 
 **NOTE**: If it is needed to install Mistral using devstack, please refer to
-:doc:`Mistral Devstack Installation </developer/contributor/devstack>`
+:doc:`Mistral Devstack Installation <../../contributor/devstack>`
 
 First of all, clone the repo and go to the repo directory::
 

doc/source/conf.py

@@ -56,7 +56,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Mistral'
-copyright = '2020, Mistral Contributors'
+copyright = '2023, Mistral Contributors'
 
 policy_generator_config_file = \
     '../../tools/config/policy-generator.mistral.conf'

doc/source/contributor/contributing.rst

@@ -1,9 +1,105 @@
-.. This file exist only because there's a requirement to have the file
+============================
-   'contributing.rst' under the folder 'doc/source/contributor' according
+So You Want to Contribute...
-   to https://governance.openstack.org/tc/goals/selected/ussuri/project-ptl-and-contrib-docs.html#completion-criteria
+============================
-   It generally conflicts with the approach taken in Mistral to divide
+
-   all the docs into the three main categories: admin, developer, and user.
+For general information on contributing to OpenStack, please check out the
-   So to avoid duplicating the content of the file we just use a directive
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
-   for inclusion.
+It covers all the basics that are common to all OpenStack projects: the accounts
+you need, the basics of interacting with our Gerrit review system, how we
+communicate as a community, etc.
+
+Below will cover the more project specific information you need to get started
+with Mistral.
+
+Communication
+~~~~~~~~~~~~~
+
+* IRC channel #openstack-mistral at `OFTC`_
+* Mailing list (prefix subjects with ``[mistral]`` for faster responses)
+  http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
+
+.. _`OFTC`: https://www.oftc.net
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+   * Renat Akhmerov (#rakhmerov)
+   * Eyal Bar-Ilan (#eyalb)
+   * Oleg Ovcharuk (#vgvoleg)
+   * Andras Kovi (#akovi)
+   * Adriano Petrich (#apetrich)
+   * Axel Vanzaghi (#avanzaghi)
+   * Arnaud Morin (#amorin)
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+
+If you want to add new functionality to Mistral please file a blueprint
+by following https://blueprints.launchpad.net/mistral/+addspec
+
+We don't have a strict requirement to write a detailed specification for
+all new features and rather encourage more agile approach: just file a
+brief description of a feature in the form of blueprint and then send a
+patch to review (linking it to the blueprint). However, in some rare cases,
+like proposing new API or workflow language additions, we need a spec so
+that the team could fully understand what's going to be done and provide
+a feedback.
+
+To file a specification for a new feature, send a patch to
+https://opendev.org/openstack/mistral-specs that adds a new spec file
+for the needed release cycle (e.g. 'specs/victoria')
+
+The full list of the specs can be seen at
+https://specs.openstack.org/openstack/mistral-specs/
+
+Task Tracking
+~~~~~~~~~~~~~
+
+We track our tasks in Launchpad: https://bugs.launchpad.net/mistral
+
+If you're looking for some smaller, easier work item to pick up and get started
+on, search for the 'low-hanging-fruit' tag.
+
+Reporting a Bug
+~~~~~~~~~~~~~~~
+
+You found an issue and want to make sure we are aware of it? You can do so on
+`Launchpad <https://bugs.launchpad.net/mistral>`_.
+
+Where to Make Code Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mistral has a number of repositories where you can make code changes:
+
+* https://github.com/openstack/mistral
+* https://github.com/openstack/python-mistralclient
+* https://github.com/openstack/mistral-dashboard
+* https://github.com/openstack/mistral-extra
+* https://github.com/openstack/mistral-lib
+* https://github.com/openstack/mistral-specs
+
+Where to Review Code Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* https://review.opendev.org/#/q/mistral
+* https://review.opendev.org/#/q/python-mistralclient
+* https://review.opendev.org/#/q/mistral-dashboard
+* https://review.opendev.org/#/q/mistral-extra
+* https://review.opendev.org/#/q/mistral-lib
+* https://review.opendev.org/#/q/mistral-specs
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Typically a patch can be merged when it has two +2 votes (at least two core
+members voted +2). In some rare emergency cases we allow one +2 vote before
+approving it.
+
+A patch cannot be merged if it has at least one negative vote!
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+All common PTL duties are enumerated in the `PTL guide
+<https://docs.openstack.org/project-team-guide/ptl.html>`_.
 
-.. include:: ../developer/contributor/contributing.rst

doc/source/contributor/debugging_and_testing.rst

@@ -101,13 +101,13 @@ To run unit tests against a specific python version:
 
 .. code-block:: bash
 
-    $ tox -e py35
+    $ tox -e py3
 
 To run tests from a specific test class (using a specific python version):
 
 .. code-block:: bash
 
-    tox -e py35 -- 'DataFlowEngineTest'
+    tox -e py3 -- 'DataFlowEngineTest'
 
 Integration tests
 -----------------
@@ -142,3 +142,75 @@ To run integration tests:
   * set 'auth_enable=false' in the mistral.conf under [pecan] group
   * restart Mistral server
   * execute: ./run_functional_tests
+
+Mistral-Dashboard debug instructions
+====================================
+
+**Pycharm**
+
+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:
+
+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
+  c. Settings: openstack_dashboard/settings.py (under your Horizon folder)
+  d. Manage script: manage.py (also in your horizon folder)
+  e. Click OK
+
+.. 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
+
+3. In the new window, click the green plus icon and then select "Django server"
+   to create a new Django Server configuration.
+
+4. In the new window appeared:
+
+  a. Name that configuration Horizon
+  b. Enter some port so it won't run on the default (for example - port: 4000)
+
+.. image:: img/dashboard_debug_config.png
+
+5. Click on Environment variables button, then in the new window:
+
+  a. Make sure you have PYTHONUNBUFFERED set as 1
+  b. Create a new pair - DJANGO_SETTINGS_MODULE : openstack_dashboard.settings
+  c. When finished click OK.
+
+.. image:: img/dashboard_environment_variables.png
+
+
+You should now be able to debug and run the project using PyCharm.
+PyCharm will listen to any changes you make
+and restart the Horizon server automatically.
+
+**Note**: When executing the project via PyCharm Run / Debug,
+you could get an error page
+after trying to login: "Page not found (404)".
+To resolve that - remove the port from the browser URL bar,
+then login.
+You should be able to login without it.
+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>`_
+
+- If you would like to manually restart the apache server,
+  open a terminal and run::
+
+    $ sudo service apache2 restart
+
+  *(if not under Ubuntu, replace "sudo" with an identical command)*

doc/source/contributor/devstack.rst

@@ -0,0 +1,17 @@
+=============================
+Mistral Devstack Installation
+=============================
+
+First, install devstack, see the following link for this:
+`Devstack Installation <https://docs.openstack.org/devstack/latest/>`_
+
+
+Before running ``stack.sh``, enable mistral plugin by editing your
+``local.conf`` file to add:
+
+    enable_plugin mistral https://github.com/openstack/mistral
+
+
+Finally, run ``stack.sh``
+
+The mistral code will land in /opt/stack/mistral

doc/source/contributor/extensions/index.rst

@@ -3,7 +3,7 @@ Writing Mistral Extensions
 ==========================
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    creating_custom_action
    extending_yaql

doc/source/contributor/index.rst

@@ -6,8 +6,8 @@ Contributor Documentation
    :maxdepth: 3
 
    contributing
+   devstack
    coding_guidelines
    debugging_and_testing
    profiling
-   troubleshooting
+   extensions/index
-   devstack

doc/source/developer/contributor/contributing.rst

@@ -1,103 +0,0 @@
-============================
-So You Want to Contribute...
-============================
-
-For general information on contributing to OpenStack, please check out the
-`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
-It covers all the basics that are common to all OpenStack projects: the accounts
-you need, the basics of interacting with our Gerrit review system, how we
-communicate as a community, etc.
-
-Below will cover the more project specific information you need to get started
-with Mistral.
-
-Communication
-~~~~~~~~~~~~~
-
-* IRC channel #openstack-mistral at `OFTC`_
-* Mailing list (prefix subjects with ``[mistral]`` for faster responses)
-  http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
-
-.. _`OFTC`: https://www.oftc.net
-
-Contacting the Core Team
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-   * Renat Akhmerov, PTL (#rakhmerov)
-   * Eyal Bar-Ilan (#eyalb)
-   * Oleg Ovcharuk (#vgvoleg)
-   * Andras Kovi (#akovi)
-   * Adriano Petrich (#apetrich)
-
-New Feature Planning
-~~~~~~~~~~~~~~~~~~~~
-
-If you want to add new functionality to Mistral please file a blueprint
-by following https://blueprints.launchpad.net/mistral/+addspec
-
-We don't have a strict requirement to write a detailed specification for
-all new features and rather encourage more agile approach: just file a
-brief description of a feature in the form of blueprint and then send a
-patch to review (linking it to the blueprint). However, in some rare cases,
-like proposing new API or workflow language additions, we need a spec so
-that the team could fully understand what's going to be done and provide
-a feedback.
-
-To file a specification for a new feature, send a patch to
-https://opendev.org/openstack/mistral-specs that adds a new spec file
-for the needed release cycle (e.g. 'specs/victoria')
-
-The full list of the specs can be seen at
-https://specs.openstack.org/openstack/mistral-specs/
-
-Task Tracking
-~~~~~~~~~~~~~
-
-We track our tasks in Launchpad: https://bugs.launchpad.net/mistral
-
-If you're looking for some smaller, easier work item to pick up and get started
-on, search for the 'low-hanging-fruit' tag.
-
-Reporting a Bug
-~~~~~~~~~~~~~~~
-
-You found an issue and want to make sure we are aware of it? You can do so on
-`Launchpad <https://bugs.launchpad.net/mistral>`_.
-
-Where to Make Code Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Mistral has a number of repositories where you can make code changes:
-
-* https://github.com/openstack/mistral
-* https://github.com/openstack/python-mistralclient
-* https://github.com/openstack/mistral-dashboard
-* https://github.com/openstack/mistral-extra
-* https://github.com/openstack/mistral-lib
-* https://github.com/openstack/mistral-specs
-
-Where to Review Code Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* https://review.opendev.org/#/q/mistral
-* https://review.opendev.org/#/q/python-mistralclient
-* https://review.opendev.org/#/q/mistral-dashboard
-* https://review.opendev.org/#/q/mistral-extra
-* https://review.opendev.org/#/q/mistral-lib
-* https://review.opendev.org/#/q/mistral-specs
-
-Getting Your Patch Merged
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Typically a patch can be merged when it has two +2 votes (at least two core
-members voted +2). In some rare emergency cases we allow one +2 vote before
-approving it.
-
-A patch cannot be merged if it has at least one negative vote!
-
-Project Team Lead Duties
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-All common PTL duties are enumerated in the `PTL guide
-<https://docs.openstack.org/project-team-guide/ptl.html>`_.
-

doc/source/developer/contributor/devstack.rst

@@ -1,13 +0,0 @@
-Mistral Devstack Installation
-=============================
-
-1. Download DevStack::
-
-    $ git clone https://github.com/openstack-dev/devstack.git
-    $ cd devstack
-
-2. Add this repo as an external repository, edit ``localrc`` file::
-
-     enable_plugin mistral https://github.com/openstack/mistral
-
-3. Run ``stack.sh``

doc/source/developer/contributor/troubleshooting.rst

@@ -1,75 +0,0 @@
-=============================
-Troubleshooting And Debugging
-=============================
-
-Mistral-Dashboard debug instructions
-====================================
-
-**Pycharm**
-
-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:
-
-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
-  c. Settings: openstack_dashboard/settings.py (under your Horizon folder)
-  d. Manage script: manage.py (also in your horizon folder)
-  e. Click OK
-
-.. 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
-
-3. In the new window, click the green plus icon and then select "Django server"
-   to create a new Django Server configuration.
-
-4. In the new window appeared:
-
-  a. Name that configuration Horizon
-  b. Enter some port so it won't run on the default (for example - port: 4000)
-
-.. image:: img/dashboard_debug_config.png
-
-5. Click on Environment variables button, then in the new window:
-
-  a. Make sure you have PYTHONUNBUFFERED set as 1
-  b. Create a new pair - DJANGO_SETTINGS_MODULE : openstack_dashboard.settings
-  c. When finished click OK.
-
-.. image:: img/dashboard_environment_variables.png
-
-
-You should now be able to debug and run the project using PyCharm.
-PyCharm will listen to any changes you make
-and restart the Horizon server automatically.
-
-**Note**: When executing the project via PyCharm Run / Debug,
-you could get an error page
-after trying to login: "Page not found (404)".
-To resolve that - remove the port from the browser URL bar,
-then login.
-You should be able to login without it.
-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>`_
-
-- If you would like to manually restart the apache server,
-  open a terminal and run::
-
-    $ sudo service apache2 restart
-
-  *(if not under Ubuntu, replace "sudo" with an identical command)*

doc/source/developer/index.rst

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

doc/source/index.rst

@@ -57,13 +57,8 @@ For Administrators and Operators
 For Developers
 ==============
 
-* :doc:`developer/contributor/coding_guidelines`: No matter what you're
+* :doc:`contributor/index`: If you want to contribute to the project or
-  going to develop regarding Mistral, please read the coding guidelines
-  we accept in our project.
-* :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)
 ==================================
@@ -81,12 +76,7 @@ Main Chapters
 
     user/index
     admin/index
-    developer/index
+    contributor/index
-
-.. toctree::
-   :hidden:
-
-   contributor/contributing
 
 .. only:: html
 

doc/source/user/terminology/actions.rst

@@ -28,7 +28,7 @@ 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 create a custom action
-</developer/extensions/creating_custom_action>`
+<../../contributor/extensions/creating_custom_action>`
 
 
 Ad-hoc actions