Update notes entry for new dynamic runner loading

Makefile

@@ -16,6 +16,7 @@ BINARIES := bin
 
 # All components are prefixed by st2
 COMPONENTS := $(wildcard st2*)
+COMPONENTS_RUNNERS := $(wildcard st2/contrib/runners/*)
 
 # Components that implement a component-controlled test-runner. These components provide an
 # in-component Makefile. (Temporary fix until I can generalize the pecan unittest setup. -mar)
@@ -27,8 +28,6 @@ space_char :=
 space_char +=
 comma := ,
 COMPONENT_PYTHONPATH = $(subst $(space_char),:,$(realpath $(COMPONENTS)))
-COMPONENTS_TEST := $(foreach component,$(filter-out $(COMPONENT_SPECIFIC_TESTS),$(COMPONENTS)),$(component))
-COMPONENTS_TEST_COMMA := $(subst $(space_char),$(comma),$(COMPONENTS_TEST))
 
 PYTHON_TARGET := 2.7
 
@@ -43,7 +42,7 @@ endif
 all: requirements check tests docs
 
 .PHONY: docs
-docs: .clone-st2 .clone-orquesta requirements .requirements-st2 .docs
+docs: .clone-st2 .clone-orquesta requirements .requirements-st2 .install-runners .docs
 
 PHONY: .docs
 .docs: .community-docs
@@ -99,7 +98,7 @@ livedocs: docs .livedocs
 	@echo
 
 .PHONY: ewcdocs
-ewcdocs: .clone-st2 .clone-orquesta .clone-ipfabric requirements .requirements-st2 .ewcdocs
+ewcdocs: .clone-st2 .clone-orquesta .clone-ipfabric requirements .requirements-st2 .install-runners .ewcdocs
 
 .PHONY: .ewcdocs
 .ewcdocs: .patch-solutions .enterprise-docs .git-checkout-local-changes
@@ -190,6 +189,18 @@ $(VIRTUALENV_DIR)/bin/activate:
 	echo 'end' >> $(VIRTUALENV_DIR)/bin/activate.fish
 	touch $(VIRTUALENV_DIR)/bin/activate.fish
 
+.PHONY: .install-runners
+.install-runners:
+	@echo ""
+	@echo "================== install runners ===================="
+	@echo ""
+	@for component in $(COMPONENTS_RUNNERS); do \
+		echo "==========================================================="; \
+		echo "Installing runner:" $$component; \
+		echo "==========================================================="; \
+        (. $(ST2_VIRTUALENV_DIR)/bin/activate; cd $$component; python setup.py develop); \
+	done
+
 .PHONY: .clone-st2
 .clone-st2:
 	@echo

docs/source/upgrade_notes.rst

@@ -3,6 +3,54 @@
 Upgrade Notes
 =============
 
+.. _ref-upgrade-notes-v3-0:
+
+|st2| v3.0
+----------
+
+* Old runner names which have been deprecated in |st2| v0.9.0 have been removed. If you still have
+  any actions which refer to runners using old names you need to update them to keep them working.
+
+  * ``run-local`` -> ``local-shell-cmd``
+  * ``run-local-script`` -> ``local-shell-script``
+  * ``run-remote`` -> ``remote-shell-cmd``
+  * ``run-remote-script`` -> ``remote-shell-script``
+  * ``run-python`` -> ``python-script``
+  * ``run-http`` -> ``http-request``
+* In |st2| v2.7 action runner modules have been refactored so they are now fully standalone and
+  re-distributable Python packages.
+
+  In this release we updated our runner loading mechanism which makes ``/opt/stackstorm/runners``
+  directory obsolete.
+
+  All the runners are now installed as Python packages into |st2| virtual environment
+  (``/opt/stackstorm/st2``) during package build process and dynamically loaded when requested.
+
+  This provides for more flexible installation and loading of runner modules. To install a custom
+  runner, user now just needs to install Python package which contains runner module into |st2|
+  virtual environment and restart |st2| services (``sudo st2ctl restart``) or run
+  ``sudo st2ctl reload --register-runners`` command.
+
+  Keep in mind that all the runners which are installed inside |st2| virtual environment are now
+  automatically loaded and registered on each |st2| service start up. You only need to run 
+  ``sudo st2ctl reload --register-runners`` if you are using runner outside the service context or
+  if you didn't restart the services.
+
+  For examples:
+
+  .. code-block:: bash
+
+   /opt/stackstorm/st2/bin/pip install "git+https://github.com/stackstorm/st2.git#egg=stackstorm-runner-cloudslang&subdirectory=contrib/runners/cloudslang_runner"
+
+   sudo st2ctl reload --register-runners
+
+  This change also makes ``content.runners_base_paths`` and ``content.system_runners_base_paths``
+  config option obsolete and unused.
+
+  If you previously had any custom runners installed in ``/opt/stackstorm/runners/`` directory, you
+  need to make sure they follow Python package specification and install them in StackStorm virtual
+  environment.
+
 .. _ref-upgrade-notes-v2-9:
 
 |st2| v2.9

scripts/generate-runner-parameters-documentation.py

@@ -21,60 +21,40 @@
 
 import os
 
-import yaml
+from st2common.runners import get_available_backends
+from st2common.runners import get_backend_instance
 
-from st2common.content.loader import RunnersLoader, RUNNER_MANIFEST_FILE_NAME
+__all__ = [
+    'main'
+]
 
 
 CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
 HEADER = '.. NOTE: This file has been generated automatically, don\'t manually edit it'
 
 
-def _get_runners_dir():
-    runner_loader = RunnersLoader()
-    runner_dir = os.path.join(CURRENT_DIR, '../st2/contrib/runners')
-
-    runner_types = runner_loader.get_runners([runner_dir])
-
-    return runner_types
-
-
-def _get_runners():
-    runners = []
-    runners_dir = _get_runners_dir()
-
-    for runner, runner_dir in runners_dir.iteritems():
-        manifest_path = os.path.join(runner_dir, RUNNER_MANIFEST_FILE_NAME)
-
-        with open(manifest_path, 'r') as manifest_file:
-            manifest_contents = manifest_file.read()
-            manifest = yaml.load(manifest_contents)
-
-            runners.extend(manifest)
-
-    return runners
-
-
-RUNNER_TYPES = _get_runners()
-
 def main():
-    for runner in RUNNER_TYPES:
-        if runner.get('experimental', False):
+    runner_names = get_available_backends()
+    for runner_name in runner_names:
+        runner_driver = get_backend_instance(runner_name)
+        runner_metadata = runner_driver .get_metadata()
+
+        if runner_metadata.get('experimental', False):
             continue
 
         result = []
         result.append(HEADER)
         result.append('')
 
-        runner_parameters = runner.get('runner_parameters', None)
+        runner_parameters = runner_metadata.get('runner_parameters', None)
         if runner_parameters:
             for name, values in runner_parameters.items():
                 format_values = {'name': name}
                 format_values.update(values)
                 line = '* ``%(name)s`` (%(type)s) - %(description)s' % format_values
                 result.append(line)
 
-            file_name = runner['name'].replace('-', '_')
+            file_name = runner_metadata['name'].replace('-', '_')
             path = '../docs/source/_includes/runner_parameters/%s.rst' % (file_name)
             destination_path = os.path.join(CURRENT_DIR, path)
             result = '\n'.join(result)