Merge pull request #331 from warrenvw/st2docs

Author: warrenvw

README.md

@@ -116,10 +116,10 @@ sphinx-autobuild -H 127.0.0.1 -b html ./docs/source/ ./docs/build/html
         st2 trigger list
 
 * Reference the document
-
-    :doc:`/start`
-    :doc:`in the Rules doc </rules>`
-
+```
+       :doc:`/start`
+       :doc:`in the Rules doc </rules>`
+```
 * Referencing an arbitrary section: for instance, there's examples section in sensors.rst. Define a reference on `examples` section in sensors.rst:
 
          .. _sensors-examples:
@@ -145,14 +145,17 @@ sphinx-autobuild -H 127.0.0.1 -b html ./docs/source/ ./docs/build/html
 
     :github_st2:`st2/st2common/st2common/operators.py </st2common/st2common/operators.py>`
 
-* Link  to Github st2contrib repo:
+* Link to Github StackStorm-Exchange org:
+
+    :github_exchange:`Link to a sensu pack repo inside Exchange<stackstorm-sensu>`
+
+* Link to StackStorm Exchange website with a filter query:
 
-    :github_contrib:`Link to docker README on st2contrib<packs/docker/README.md>`
+    :web_exchange:`Sensu<sensu>`
 
-* Link to st2contrib and st2incubator repos on Github (using a global we set up in source/conf.py)
+* Link to the Exchange website on Github (using a global we set up in source/conf.py)
 
-    `st2contrib`_
-    `st2incubator`_
+    `exchange`_
 
 * The pattern to include an example from `/st2/contrib/examples`: make example file name a reference on github. May say that it is deployed to `/usr/share/doc/st2/examples/`, and auto-include the file:
 

docs/source/_includes/config_yaml_deprecation_notice.rst

@@ -0,0 +1,14 @@
+.. note::
+
+    All the information on this page refers to the config files inside the
+    ``/opt/stackstorm/configs/`` directory.
+
+    config.yaml files inside the pack directory have been deprecated in |st2|
+    v1.5. Values from config.yaml file **don't** get saved in the database when
+    running ``st2 reload --register-configs`` and those configs also don't
+    support config schemas.
+
+    For backward compatibility, if a pack doesn't contain a config inside the
+    ``/opt/stackstorm/configs/`` directory, values from config.yaml are still
+    used when running an action, but support for config.yaml files inside the
+    pack directory will be fully removed in the next major release.

docs/source/_includes/runner_parameters/python_script.rst

@@ -1,4 +1,4 @@
 .. NOTE: This file has been generated automatically, don't manually edit it
 
-* ``env`` (object) - Environment variables which will be available to the script(e.g. key1=val1,key2=val2)
+* ``env`` (object) - Environment variables which will be available to the script.
 * ``timeout`` (integer) - Action timeout in seconds. Action will get killed if it doesn't finish in timeout seconds.

docs/source/_static/images/packs-chatops-get.png

@@ -412,7 +412,7 @@ are serialized based on the simple rules described below:
 1. ``string``, ``integer``, ``float`` - Serialized as a string.
 2. ``boolean`` - Serialized as a string ``1`` (true) or ``0`` (false).
 3. ``lists`` - Serialized as a comma delimited string (e.g. ``foo,bar,baz``).
-4. ``objects`` - Serialized as JSON.
+4. ``object`` - Serialized as JSON.
 
 Using this simple serialization format allows users to easily utilize those
 values in their scripts by using standard Bash functionality (``-z`` for check
@@ -552,7 +552,7 @@ passed in, action will be considered as failed (first flag in the result tuple
 indicating action status is ``False``).
 
 For a more complex example, please refer to the `actions in the Libcloud pack in
-the contrib repository <https://github.com/StackStorm/st2contrib/tree/master/packs/libcloud/actions>`_.
+StackStorm Exchange <https://github.com/StackStorm-Exchange/libcloud/tree/master/actions>`_.
 
 Configuration File
 ~~~~~~~~~~~~~~~~~~
@@ -632,7 +632,7 @@ Pre-defined Actions
 ^^^^^^^^^^^^^^^^^^^
 
 There are several predefined actions that come out of the box when |st2|
-is installed via packages.
+is installed via packages. These are in the ``core`` pack:
 
 ``core.local`` : This action allows execution of arbitrary \*nix/shell commands
 locally. You can excute this command via the CLI using:
@@ -662,15 +662,15 @@ and password:
 
     st2 run core.http url="http://httpbin.org/get" method="GET" username=user1 password=pass1
 
-To see all predefined actions:
+To see all actions in the ``core`` pack:
 
 ::
 
     st2 action list --pack=core
 
 .. rubric:: What's Next?
 
-* Explore packs and actions contributed by |st2| developers and community in the `StackStorm st2contrib repo on Github <https://github.com/StackStorm/st2contrib/>`_.
+* Explore packs and actions contributed by |st2| developers and community in the `StackStorm Exchange <https://exchange.stackstorm.org>`_.
 * Check out `tutorials on stackstorm.com <http://stackstorm.com/category/tutorials/>`__ on creating actions, and other practical examples of automating with |st2|.
 
 .. _JSON Schema: http://json-schema.org/documentation.html

docs/source/_static/images/packs-chatops-install.png

@@ -4,7 +4,7 @@ Notifications
 If you read through the :ref:`ref-chatops` section, you are familiar with notifications.
 Even without ChatOps, notifications can be used to post messages to external systems
 like Chat clients, send emails etc. Notifications require an action that is registered with
-|st2| (e.g., the `post_message <https://github.com/StackStorm/st2contrib/blob/master/packs/slack/actions/post_message.yaml>`_ action in the the ``slack`` pack)
+|st2| (e.g., the `post_message <https://github.com/StackStorm-Exchange/stackstorm-slack/tree/master/actions/post_message.yaml>`_ action in the the ``slack`` pack)
 and a notification rule to go with it. Notifications are implemented as triggers, rules and actions.
 A special ``core.st2.notifytrigger`` is emitted by the system on completion of every action.
 A rule to match the trigger to a notify action results in notifications being sent out.

docs/source/_static/images/packs-chatops-search.png

@@ -1,89 +1,78 @@
 Packs
 =====
 
-Installing packs from st2incubator or st2contrib via ChatOps
-------------------------------------------------------------
+Installing packs with ChatOps
+-----------------------------
 
-When you have the bot listening for ChatOps commands in a channel, installing extra packs 
-can be done by running a single command:
+When you have the bot listening for ChatOps commands in a channel, installing extra packs
+from StackStorm Exchange can be done by running a single command:
 
 .. code-block:: bash
 
-    ! pack deploy st2contrib elasticsearch,travis_ci
-    bot: Deploying the requested pack(s) from *st2contrib* for you....
-    @my_user: Successful deployment of *elasticsearch* *travis_ci* !
-    > from https://github.com/StackStorm/st2contrib.git (branch: _master_).
+    !pack install github,slack,trello
+    bot: Installing the requested pack(s) for you.
+    @my_user:
+    > Successful deployment of *github*, *slack*, *trello* packs!
 
-If you're adventurous and wish to install and help develop a pack that's
-currently in st2incubator you can install one with the following command:
+You can install a pack from any github repository just as easily: supply the full URL
+to the bot. Pack name is unnecessary, as it will be read from ``pack.yaml`` later:
 
 .. code-block:: bash
 
-    ! pack deploy st2incubator vsphere,debian
-    Deploying the requested pack(s) from *st2incubator* for you
-    @my_user: Successful deployment of *vsphere* *debian* !
-    > from https://github.com/StackStorm/st2incubator.git (branch: _master_).
+    !pack install https://github.com/stackstorm/openstack
+    bot: Installing the requested pack(s) for you.
 
-The command takes the following very simple format:
+You can even mix the two formats in one string:
 
 .. code-block:: bash
- 
-    ! pack deploy {{repo_name}} {{packs}} {{branch=master}} - Download StackStorm packs via ChatOps
 
-Deploying Custom packs via ChatOps
-----------------------------------
+    !pack install github,slack,trello,https://github.com/stackstorm/openstack
 
-The same commands can be used to install your own packs just by adding an entry to `/opt/stackstorm/packs/packs/config.yaml` in the following format:
+.. figure :: /_static/images/packs-chatops-install.png
+    :align: center
 
-.. code-block:: yaml
 
-    ---
-    repositories:
-    NameOfRep:
-      repo: "https://github.com/<my-GitHub-user>/my-st2.git"
-      subtree: true
+Getting information about an installed pack
+-------------------------------------------
 
-This will allow you to install a pack via:
+The ``!pack get <pack>`` command shows you information about an installed
+pack. There is two sections in the output: the first is pack metadata from
+``pack.yaml``, and the optional second is git information, if your pack has
+been installed from a git source like StackStorm Exchange or a single repo.
 
-.. code-block:: bash
-
-    ! pack deploy NameOfRep MyAwesomePack
-
-If you don't have multiple packs within the same repository under a `packs` directory, just set `subtree` to `false` and issue the following command:
-
-.. code-block:: bash
+Git status will tell you if there's a difference between your local pack version
+and the latest version in the origin repository, and also show the remotes
+for your pack.
 
-    ! pack deploy NameOfRep NameOfRep
+If a pack is not installed, but available in StackStorm Exchange, the bot will
+gallantly offer to install it:
 
-Automating Custom Pack Deployment
----------------------------------
+.. figure :: /_static/images/packs-chatops-get.png
+    :align: center
 
-Building on the above it's possible to enable auto deployment for a single branch of a 
-repository which has has `subtree` set to `false` by adding an `auto_deployment` section as shown below:
+Getting information about an available pack
+-------------------------------------------
 
-.. code-block:: yaml
+The remote counterpart to ``pack get`` is ``pack show``: it will show an
+entry from the StackStorm Exchange, our pack directory, if a pack with the
+given name is available.
 
-    ---
-    repositories:
-       my-st2:
-         repo: "https://github.com/<my-GitHub-user>/my-st2.git"
-         subtree: false
-         auto_deployment:
-           branch: "master"
-           notify_channel: "my-chatops-channel"
+.. figure :: /_static/images/packs-chatops-show.png
+    :align: center
 
-Then you need a rule (or a sensor) that will trigger the `packs.deploy` action with the right 
-parameters. The following is based on an post-commit hook from BitBucket Server:
+Searching for a pack
+--------------------
 
-.. code-block:: yaml
+To search for a pack in StackStorm Exchange, use ``!pack search <query>``. Note that
+your query will match results in all pack parameters: for example, you can search for
+an author or a keyword, not just name and description. The results are ordered by
+relevance: if you search for "cloud", first you will get packs with "cloud" in their
+name—because they are the most likely to be what you were looking for—and then packs
+with "cloud" in keywords or description. And then packs authored by "Mr. Cloud", if
+any.
 
-    action:
-      ref: "packs.deploy"
-      parameters:
-        auto_deploy: true
-        repo_name:  "{{trigger.body.repository.name}}"
-        branch:     "{{trigger.body.refChanges[0].refId}}"
-        packs:      [ "{{trigger.body.repository.name}}" ]
-        message:    "{{trigger.body.changesets.get('values')[0].toCommit.message}}"
-        author:     "{{trigger.body.changesets.get('values')[0].toCommit.author.name}}"
+**Pro-tip:** if you configure an additional pack index (see "Working with pack indexes" in :doc:`/packs`),
+it will be queried alongside StackStorm Exchange by commands like ``show`` or ``search``.
 
+.. figure :: /_static/images/packs-chatops-search.png
+    :align: center