Initial commit for python-mistralclient document

This is the first document from the client side of mistral.
Taking this as a starting point, client side documentation can
be done.

Change-Id: I5a787e00bade0636da791cd7f3b3f045cdbc511a
Partial-Implements: blueprint mistral-python-client-docs

doc/source/cli_usage_with_keycloak.rst

@@ -0,0 +1,2 @@
+Using Mistral with KeyCloak Server
+==================================

doc/source/cli_usage_with_openstack.rst

@@ -0,0 +1,36 @@
+Using Mistral with OpenStack
+============================
+
+The **mistral** shell utility interacts with OpenStack Mistral API from the
+command-line. It supports the features in the OpenStack Mistral API.
+
+Basic Usage
+-----------
+
+In order to use the CLI, you must provide your OpenStack credentials
+(for both user and project), and auth endpoint. Use the corresponding
+configuration options (``--os-username``, ``--os-password``,
+``--os-project-name``, ``--os-user-domain-id``, ``os-project-domain-id``, and
+``--os-auth-url``), but it is easier to set them in environment variables.
+
+.. code-block:: shell
+
+    $ export OS_AUTH_URL=http://<Keystone_host>:5000/v2.0
+    $ export OS_USERNAME=admin
+    $ export OS_TENANT_NAME=tenant
+    $ export OS_PASSWORD=secret
+    $ export OS_MISTRAL_URL=http://<Mistral host>:8989/v2
+
+When authenticating against keystone over https:
+
+.. code-block:: shell
+
+    $ export OS_CACERT=<path_to_ca_cert>
+
+Once you've configured your authentication parameters, you can run **mistral**
+commands.  All commands take the form of::
+
+    mistral <command> [arguments...]
+
+Run **mistral --help** to get a full list of all possible commands, and run
+**mistral help <command>** to get detailed help for that command.

doc/source/cli_usage_without_auth.rst

@@ -0,0 +1,42 @@
+Using Mistral without Authentication
+====================================
+
+It is possible to execute a workflow on any arbitrary cloud without additional
+configuration on the Mistral server side. If authentication is turned off in
+the Mistral server (Pecan's `auth_enable = False` option in `mistral.conf`),
+there is no need to set the `keystone_authtoken` section. It is possible to
+have Mistral use an external OpenStack cloud even when it isn't deployed in
+an OpenStack environment (i.e. no Keystone integration).
+
+This setup is particularly useful when Mistral is used in standalone mode,
+where the Mistral service is not part of the OpenStack cloud and runs
+separately.
+
+To enable this operation, the user can use ``--os-target-username``,
+``--os-target-password``, ``--os-target-tenant-id``,
+``--os-target-tenant-name``, ``--os-target-auth-token``,
+``--os-target-auth-url``, ``--os-target_cacert``, and
+``--os-target-region-name`` parameters.
+
+For example, the user can return the heat stack list with this setup as shown
+below:
+
+.. code-block:: shell
+
+    $ mistral \
+        --os-target-auth-url=http://keystone2.example.com:5000/v3 \
+        --os-target-username=testuser \
+        --os-target-tenant=testtenant \
+        --os-target-password="MistralRuleZ" \
+        --os-mistral-url=http://mistral.example.com:8989/v2 \
+        run-action heat.stacks_list
+
+The OS-TARGET-* parameters can be set in environment variables as:
+
+.. code-block:: shell
+
+    $ export OS_TARGET_AUTH_URL=http://keystone2.example.com:5000/v3
+    $ export OS_TARGET_USERNAME=admin
+    $ export OS_TARGET_TENANT_NAME=tenant
+    $ export OS_TARGET_PASSWORD=secret
+    $ export OS_TARGET_REGION_NAME=region

doc/source/conf.py

@@ -11,14 +11,19 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-# import sys, os
+import os
-
 import pbr.version
+import subprocess
+import sys
+
+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('../'))
+sys.path.insert(0, os.path.abspath('./'))
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -26,7 +31,13 @@ import pbr.version
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'oslosphinx',
+]
+
+if not on_rtd:
+    extensions.append('oslosphinx')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -42,7 +53,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Mistral Client'
-copyright = u'2013, OpenStack Foundation'
+copyright = u'2016, Mistral Contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -71,15 +82,15 @@ exclude_patterns = []
 # default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
+add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-# add_module_names = True
+add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-# show_authors = False
+show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -92,19 +103,32 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+if on_rtd:
+    html_theme_path = ['.']
+    html_theme = 'sphinx_rtd_theme'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 # html_theme_options = {}
 
+# 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'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+           "-n1"]
+html_last_updated_fmt = subprocess.Popen(
+    git_cmd, stdout=subprocess.PIPE).communicate()[0]
+
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-# html_title = None
+html_title = 'MistralClient'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 # html_short_title = None
@@ -132,7 +156,16 @@ html_theme = 'default'
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    'index': [
+        'sidebarlinks.html', 'localtoc.html', 'searchbox.html',
+        'sourcelink.html'
+    ],
+    '**': [
+        'localtoc.html', 'relations.html',
+        'searchbox.html', 'sourcelink.html'
+    ]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -216,7 +249,7 @@ latex_documents = [
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'mistral_client', u'Mistral Client Documentation',
-     [u'OpenStack Foundation'], 1)
+     [u'Mistral Contributors'], 1)
 ]
 
 # If true, show URL addresses after external links.

doc/source/index.rst

@@ -1,17 +1,39 @@
-Welcome to Mistral Client documentation!
+Python bindings to the OpenStack Workflow API
-========================================
+=============================================
 
-Contents:
+This is a client for OpenStack Mistral API. There's a Python API
+(the :mod:`mistralclient` module), and a command-line script
+(installed as :program:`mistral`).
+
+Using mistralclient
+-------------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   cli_usage_with_openstack
+   cli_usage_with_keycloak
+   cli_usage_without_auth
 
+For information about using the mistral command-line client, see
+`Workflow service command-line client`_.
 
-Indices and tables
+.. _Workflow service command-line client: http://docs.openstack.org/cli-reference/mistral.html
-==================
 
-* :ref:`genindex`
+Python API Reference
-* :ref:`modindex`
+--------------------
-* :ref:`search`
 
+* `REST API Specification`_
+
+.. _REST API Specification: http://docs.openstack.org/developer/mistral/developer/webapi/v2.html
+
+Contributing
+------------
+
+Code is hosted `on GitHub`_. Submit bugs to the python-mistralclient project on
+`Launchpad`_. Submit code to the openstack/python-heatclient project
+using `Gerrit`_.
+
+.. _on GitHub: https://github.com/openstack/python-mistralclient
+.. _Launchpad: https://launchpad.net/python-mistralclient
+.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow