From d27f91ac6179572fbeacf55cdf871afeca527292 Mon Sep 17 00:00:00 2001 From: Sharat Sharma Date: Wed, 30 Nov 2016 17:09:54 +0530 Subject: [PATCH] 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 | 2 + doc/source/cli_usage_with_openstack.rst | 36 +++++++++++++++ doc/source/cli_usage_without_auth.rst | 42 ++++++++++++++++++ doc/source/conf.py | 59 +++++++++++++++++++------ doc/source/index.rst | 40 +++++++++++++---- 5 files changed, 157 insertions(+), 22 deletions(-) create mode 100644 doc/source/cli_usage_with_keycloak.rst create mode 100644 doc/source/cli_usage_with_openstack.rst create mode 100644 doc/source/cli_usage_without_auth.rst diff --git a/doc/source/cli_usage_with_keycloak.rst b/doc/source/cli_usage_with_keycloak.rst new file mode 100644 index 00000000..31ebc553 --- /dev/null +++ b/doc/source/cli_usage_with_keycloak.rst @@ -0,0 +1,2 @@ +Using Mistral with KeyCloak Server +================================== diff --git a/doc/source/cli_usage_with_openstack.rst b/doc/source/cli_usage_with_openstack.rst new file mode 100644 index 00000000..b1cf84c5 --- /dev/null +++ b/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://:5000/v2.0 + $ export OS_USERNAME=admin + $ export OS_TENANT_NAME=tenant + $ export OS_PASSWORD=secret + $ export OS_MISTRAL_URL=http://:8989/v2 + +When authenticating against keystone over https: + +.. code-block:: shell + + $ export OS_CACERT= + +Once you've configured your authentication parameters, you can run **mistral** +commands. All commands take the form of:: + + mistral [arguments...] + +Run **mistral --help** to get a full list of all possible commands, and run +**mistral help ** to get detailed help for that command. diff --git a/doc/source/cli_usage_without_auth.rst b/doc/source/cli_usage_without_auth.rst new file mode 100644 index 00000000..b4ef6f85 --- /dev/null +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 30aa6a1e..e64f9b3c 100644 --- a/doc/source/conf.py +++ b/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 # " v 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index d47f7ad2..369b501c 100644 --- a/doc/source/index.rst +++ b/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` -* :ref:`modindex` -* :ref:`search` +Python API Reference +-------------------- +* `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