Add autogenerated API documentation

Change-Id: I859be6d47d58fee13875d02a7839864348829687

doc/source/conf.py

@@ -1,245 +1,79 @@
 # -*- coding: utf-8 -*-
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# Mistral documentation build configuration file, created by
+#    http://www.apache.org/licenses/LICENSE-2.0
-# sphinx-quickstart on Fri Nov  1 02:06:28 2013.
 #
-# This file is execfile()d with the current directory set to its containing
+# Unless required by applicable law or agreed to in writing, software
-# dir.
+# distributed under the License is distributed on an "AS IS" BASIS,
-#
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-# Note that not all possible configuration values are present in this
+# implied.
-# autogenerated file.
+# See the License for the specific language governing permissions and
-#
+# limitations under the License.
-# All configuration values have a default; values that are commented out
-# serve to show the default.
 
-# import sys, os
+import os
+import sys
 
-# If extensions (or modules to document with autodoc) are in another directory,
+sys.path.insert(0, os.path.abspath('../..'))
-# add these directories to sys.path here. If the directory is relative to the
+# -- General configuration ----------------------------------------------------
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
 
 # 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',
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib.autohttp.flask',
+    'sphinxcontrib.pecanwsme.rest',
+    'oslosphinx',
+    'wsmeext.sphinxext',
+]
 
-# Add any paths that contain templates here, relative to this directory.
+wsme_protocols = ['restjson', 'restxml']
-templates_path = ['_templates']
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'Mistral'
+project = u'mistral'
-copyright = u'2013, OpenStack Foundation'
+copyright = u'2014, 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
-# built documents.
-#
-# The short X.Y version.
-version = '0.01'
-# The full version, including alpha/beta/rc tags.
-release = '0.01'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = []
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#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
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for module index sorting.
+# -- Options for HTML output --------------------------------------------------
-#modindex_common_prefix = []
 
-
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# -- Options for HTML output -------------------------------------------------
+# Sphinx are currently 'default' and 'sphinxdoc'.
-
+# html_theme_path = ["."]
-# The theme to use for HTML and HTML Help pages.  See the documentation for
+# html_theme = '_theme'
-# a list of builtin themes.
-html_theme = 'default'
-
-# 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 = {}
-
-# 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
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# 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'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Mistraldoc'
+htmlhelp_basename = '%sdoc' % project
 
-
+# -- Options for manual page output -------------------------------------------
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author,
-#  documentclass [howto/manual]).
-latex_documents = [
-    ('index', 'Mistral.tex', u'Mistral Documentation',
-     u'OpenStack Foundation', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
+man_pages = []
-    ('index', 'mistral', u'Mistral Documentation',
-     [u'OpenStack Foundation'], 1)
-]
 
 # If true, show URL addresses after external links.
-#man_show_urls = False
+man_show_urls = True
 
-
+# Example configuration for intersphinx: refer to the Python standard library.
-# -- Options for Texinfo output ----------------------------------------------
+intersphinx_mapping = {'http://docs.python.org/': None}
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    ('index', 'Mistral', u'Mistral Documentation',
-     u'OpenStack Foundation', 'Mistral', 'One line description of project.',
-     'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'

doc/source/develop_applications/index.rst

@@ -0,0 +1,7 @@
+Developing using Mistral
+========================
+
+.. toctree::
+   :maxdepth: 3
+
+   webapi/index

doc/source/develop_applications/webapi/index.rst

@@ -0,0 +1,8 @@
+API Complete Reference
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   root
+   v1

doc/source/develop_applications/webapi/root.rst

@@ -0,0 +1,8 @@
+API
+===
+
+Root
+----
+
+.. autotype:: mistral.api.controllers.root:APIVersion
+   :members:

doc/source/develop_applications/webapi/v1.rst

@@ -0,0 +1,58 @@
+V1 API
+======
+
+.. autotype:: mistral.api.controllers.resource.Link
+   :members:
+
+Workbooks
+---------
+
+.. rest-controller:: mistral.api.controllers.v1.workbook:WorkbooksController
+   :webprefix: /v1/workbooks
+
+.. autotype:: mistral.api.controllers.v1.workbook.Workbooks
+   :members:
+
+.. autotype:: mistral.api.controllers.v1.workbook.Workbook
+   :members:
+
+Workbook Definitions
+--------------------
+
+.. rest-controller:: mistral.api.controllers.v1.workbook_definition:WorkbookDefinitionController
+   :webprefix: /v1/workbooks/definition
+
+Executions
+----------
+.. rest-controller:: mistral.api.controllers.v1.execution:ExecutionsController
+   :webprefix: /v1/workbooks/executions
+
+.. autotype:: mistral.api.controllers.v1.execution.Executions
+   :members:
+
+.. autotype:: mistral.api.controllers.v1.execution.Execution
+   :members:
+
+Listeners
+---------
+.. rest-controller:: mistral.api.controllers.v1.listener:ListenersController
+   :webprefix: /v1/workbooks/listeners
+
+.. autotype:: mistral.api.controllers.v1.listener.Listeners
+   :members:
+
+.. autotype:: mistral.api.controllers.v1.listener.Listener
+   :members:
+
+
+Tasks
+-----
+
+.. rest-controller:: mistral.api.controllers.v1.task:TasksController
+   :webprefix: /v1/workbooks/executions/tasks
+
+.. autotype:: mistral.api.controllers.v1.task.Tasks
+   :members:
+
+.. autotype:: mistral.api.controllers.v1.task.Task
+   :members:

doc/source/index.rst

@@ -11,7 +11,8 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-
+   readme
+   develop_applications/index
 
 Indices and tables
 ==================

doc/source/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst

mistral/api/controllers/resource.py

@@ -66,3 +66,8 @@ class Link(Resource):
 
     href = wtypes.text
     target = wtypes.text
+
+    @classmethod
+    def sample(cls):
+        return cls(href='http://example.com/here',
+                   target='here')

mistral/api/controllers/root.py

@@ -31,8 +31,20 @@ class APIVersion(resource.Resource):
     """API Version."""
 
     id = wtypes.text
+    "The version identifier."
+
     status = API_STATUS
+    "The status of the API (SUPPORTED, CURRENT or DEPRECATED)."
+
     link = resource.Link
+    "The link to the versioned API."
+
+    @classmethod
+    def sample(cls):
+        return cls(id='v1.0',
+                   status='CURRENT',
+                   link=resource.Link(target_name='v1',
+                                      href='http://example.com:9777/v1'))
 
 
 class RootController(object):

mistral/api/controllers/v1/execution.py

@@ -63,12 +63,24 @@ class Execution(resource.Resource):
 
         return e
 
+    @classmethod
+    def sample(cls):
+        return cls(id='1234',
+                   workbook_name='flow',
+                   task='doit',
+                   state='SUCCESS',
+                   context='{}')
+
 
 class Executions(resource.Resource):
     """A collection of Execution resources."""
 
     executions = [Execution]
 
+    @classmethod
+    def sample(cls):
+        return cls(executions=[Execution.sample()])
+
 
 class ExecutionsController(rest.RestController):
 
@@ -77,6 +89,7 @@ class ExecutionsController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Execution, wtypes.text, wtypes.text)
     def get(self, workbook_name, id):
+        """Return the specified Execution."""
         LOG.debug("Fetch execution [workbook_name=%s, id=%s]" %
                   (workbook_name, id))
         values = db_api.execution_get(workbook_name, id)
@@ -85,6 +98,7 @@ class ExecutionsController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Execution, wtypes.text, wtypes.text, body=Execution)
     def put(self, workbook_name, id, execution):
+        """Update the specified Execution."""
         LOG.debug("Update execution [workbook_name=%s, id=%s, execution=%s]" %
                   (workbook_name, id, execution))
 
@@ -98,6 +112,7 @@ class ExecutionsController(rest.RestController):
     @wsme_pecan.wsexpose(Execution, wtypes.text, body=Execution,
                          status_code=201)
     def post(self, workbook_name, execution):
+        """Create a new Execution."""
         LOG.debug("Create execution [workbook_name=%s, execution=%s]" %
                   (workbook_name, execution))
 
@@ -115,12 +130,14 @@ class ExecutionsController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(None, wtypes.text, wtypes.text, status_code=204)
     def delete(self, workbook_name, id):
+        """Delete the specified Execution."""
         LOG.debug("Delete execution [workbook_name=%s, id=%s]" %
                   (workbook_name, id))
         db_api.execution_delete(workbook_name, id)
 
     @wsme_pecan.wsexpose(Executions, wtypes.text)
     def get_all(self, workbook_name):
+        """Return all Executions."""
         LOG.debug("Fetch executions [workbook_name=%s]" % workbook_name)
 
         executions = [Execution.from_dict(values)

mistral/api/controllers/v1/listener.py

@@ -28,7 +28,10 @@ LOG = logging.getLogger(__name__)
 
 class Event(resource.Resource):
     """Event descriptor."""
-    pass
+
+    @classmethod
+    def sample(cls):
+        return cls()
 
 
 class TaskEvent(Event):
@@ -50,17 +53,30 @@ class Listener(resource.Resource):
     webhook = wtypes.text
     events = [Event]
 
+    @classmethod
+    def sample(cls):
+        return cls(id='1234',
+                   workbook_name='flow',
+                   description='listener for my flow',
+                   webhook='http://example.com/here',
+                   events=[Event.sample()])
+
 
 class Listeners(resource.Resource):
     """A collection of Listener resources."""
 
     listeners = [Listener]
 
+    @classmethod
+    def sample(cls):
+        return cls(listeners=[Listener.sample()])
+
 
 class ListenersController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Listener, wtypes.text, wtypes.text)
     def get(self, workbook_name, id):
+        """Return the specified listener."""
         LOG.debug("Fetch listener [workbook_name=%s, id=%s]" %
                   (workbook_name, id))
 
@@ -69,6 +85,7 @@ class ListenersController(rest.RestController):
 
     @wsme_pecan.wsexpose(Listener, wtypes.text, wtypes.text, body=Listener)
     def put(self, workbook_name, id, listener):
+        """Update the specified listener."""
         LOG.debug("Update listener [workbook_name=%s, id=%s, listener=%s]" %
                   (workbook_name, id, listener))
 
@@ -79,6 +96,7 @@ class ListenersController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Listener, wtypes.text, body=Listener, status_code=201)
     def post(self, workbook_name, listener):
+        """Create a new listener."""
         LOG.debug("Create listener [workbook_name=%s, listener=%s]" %
                   (workbook_name, listener))
 
@@ -89,6 +107,7 @@ class ListenersController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(None, wtypes.text, wtypes.text, status_code=204)
     def delete(self, workbook_name, id):
+        """Delete the specified listener."""
         LOG.debug("Delete listener [workbook_name=%s, id=%s]" %
                   (workbook_name, id))
 
@@ -96,6 +115,7 @@ class ListenersController(rest.RestController):
 
     @wsme_pecan.wsexpose(Listeners, wtypes.text)
     def get_all(self, workbook_name):
+        """Return all listeners."""
         LOG.debug("Fetch listeners [workbook_name=%s]" % workbook_name)
 
         listeners = [Listener.from_dict(values)

mistral/api/controllers/v1/task.py

@@ -32,6 +32,8 @@ class Task(resource.Resource):
     """Task resource."""
 
     id = wtypes.text
+    "The ID of the Task."
+
     workbook_name = wtypes.text
     execution_id = wtypes.text
     name = wtypes.text
@@ -40,17 +42,34 @@ class Task(resource.Resource):
     state = wtypes.text
     tags = [wtypes.text]
 
+    @classmethod
+    def sample(cls):
+        return cls(id='1234',
+                   workbook_name='notifier',
+                   execution_id='234',
+                   name='notifier',
+                   description='tell when you are done',
+                   action='std.email',
+                   state='OK',
+                   tags=['foo', 'fee'])
+
 
 class Tasks(resource.Resource):
     """A collection of tasks."""
 
     tasks = [Task]
+    "List of tasks."
+
+    @classmethod
+    def sample(cls):
+        return cls(tasks=[Task.sample()])
 
 
 class TasksController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Task, wtypes.text, wtypes.text, wtypes.text)
     def get(self, workbook_name, execution_id, id):
+        """Return the specified task."""
         LOG.debug("Fetch task [workbook_name=%s, execution_id=%s, id=%s]" %
                   (workbook_name, execution_id, id))
 
@@ -61,6 +80,7 @@ class TasksController(rest.RestController):
     @wsme_pecan.wsexpose(Task, wtypes.text, wtypes.text, wtypes.text,
                          body=Task)
     def put(self, workbook_name, execution_id, id, task):
+        """Update the specified task."""
         LOG.debug("Update task "
                   "[workbook_name=%s, execution_id=%s, id=%s, task=%s]" %
                   (workbook_name, execution_id, id, task))
@@ -76,6 +96,7 @@ class TasksController(rest.RestController):
 
     @wsme_pecan.wsexpose(Tasks, wtypes.text, wtypes.text)
     def get_all(self, workbook_name, execution_id):
+        """Return all tasks within the execution."""
         LOG.debug("Fetch tasks [workbook_name=%s, execution_id=%s]" %
                   (workbook_name, execution_id))
 

mistral/api/controllers/v1/workbook.py

@@ -38,12 +38,22 @@ class Workbook(resource.Resource):
     description = wtypes.text
     tags = [wtypes.text]
 
+    @classmethod
+    def sample(cls):
+        return cls(name='flow',
+                   description='my workflow',
+                   tags=['large', 'expensive'])
+
 
 class Workbooks(resource.Resource):
     """A collection of Workbooks."""
 
     workbooks = [Workbook]
 
+    @classmethod
+    def sample(cls):
+        return cls(workbooks=[Workbook.sample()])
+
 
 class WorkbooksController(rest.RestController):
     definition = workbook_definition.WorkbookDefinitionController()
@@ -53,6 +63,7 @@ class WorkbooksController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Workbook, wtypes.text)
     def get(self, name):
+        """Return the named workbook."""
         LOG.debug("Fetch workbook [name=%s]" % name)
 
         values = db_api.workbook_get(name)
@@ -61,6 +72,7 @@ class WorkbooksController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Workbook, wtypes.text, body=Workbook)
     def put(self, name, workbook):
+        """Update the named workbook."""
         LOG.debug("Update workbook [name=%s, workbook=%s]" % (name, workbook))
 
         return Workbook.from_dict(db_api.workbook_update(name,
@@ -69,6 +81,7 @@ class WorkbooksController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(Workbook, body=Workbook, status_code=201)
     def post(self, workbook):
+        """Create a new workbook."""
         LOG.debug("Create workbook [workbook=%s]" % workbook)
         wb = workbooks.create_workbook(workbook.to_dict())
         return Workbook.from_dict(wb)
@@ -76,11 +89,13 @@ class WorkbooksController(rest.RestController):
     @rest_utils.wrap_wsme_controller_exception
     @wsme_pecan.wsexpose(None, wtypes.text, status_code=204)
     def delete(self, name):
+        """Delete the named workbook."""
         LOG.debug("Delete workbook [name=%s]" % name)
         db_api.workbook_delete(name)
 
     @wsme_pecan.wsexpose(Workbooks)
     def get_all(self):
+        """return all workbooks."""
         LOG.debug("Fetch workbooks.")
 
         workbooks_list = [Workbook.from_dict(values)

mistral/api/controllers/v1/workbook_definition.py

@@ -31,6 +31,7 @@ class WorkbookDefinitionController(rest.RestController):
     @rest_utils.wrap_pecan_controller_exception
     @expose()
     def get(self, workbook_name):
+        """Return the workbook definition."""
         LOG.debug("Fetch workbook definition [workbook_name=%s]" %
                   workbook_name)
         return db_api.workbook_definition_get(workbook_name)
@@ -38,6 +39,7 @@ class WorkbookDefinitionController(rest.RestController):
     @rest_utils.wrap_pecan_controller_exception
     @expose(content_type="text/plain")
     def put(self, workbook_name):
+        """Update the workbook's definition."""
         text = request.text
 
         LOG.debug("Update workbook definition [workbook_name=%s, text=%s]" %

setup.cfg

@@ -21,6 +21,14 @@ author-email = openstack-dev@lists.openstack.org
 packages =
     mistral
 
+[build_sphinx]
+source-dir = doc/source
+build-dir = doc/build
+all_files = 1
+
+[upload_sphinx]
+upload-dir = doc/build/html
+
 [entry_points]
 console_scripts =
     mistral-server = mistral.cmd.launch:main

test-requirements.txt

@@ -4,6 +4,10 @@ flake8==2.0
 pylint==0.25.2
 sphinx>=1.1.2
 unittest2
+oslosphinx
+sphinxcontrib-pecanwsme>=0.8
+sphinxcontrib-httpdomain
+docutils==0.9.1
 fixtures>=0.3.14
 mock>=1.0
 nose