python-qinling doc improvement

Story: 2001623
Task: 6604
Change-Id: Ic3f92bf5961891fc0b51a82421edae969cdfd18c

CONTRIBUTING.rst

@@ -11,3 +11,7 @@ submitted for review via the Gerrit tool:
    http://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 Pull requests submitted through GitHub will be ignored.
+
+Bugs should be filed on Launchpad, not GitHub:
+
+   https://storyboard.openstack.org/#!/project/926

README.rst

@@ -1,30 +1,45 @@
-Qinling
-=======
+========================
+Team and repository tags
+========================
 
-Qinling is Function as a Service for OpenStack. This project aims to provide a
-platform to support serverless functions (like AWS Lambda). Qinling supports
-different container orchestration platforms (Kubernetes/Swarm, etc.) and
-different function package storage backends (local/Swift/S3) by nature using
-plugin mechanism.
+.. image:: https://governance.openstack.org/tc/badges/python-qinlingclient.svg
+    :target: https://governance.openstack.org/reference/tags/index.html
 
-Python Qinlingclient
---------------------
-python-qinlingclient is a client library for Qinling built on the Qinling API.
-It provides a Python API (the ``qinlingclient`` module) and an openstack
-command-line tool.
+.. Change things from this point on
 
-Project Resources
------------------
+====================
+python-qinlingclient
+====================
 
-Project status, bugs, and blueprints are tracked on Launchpad:
+This is an OpenStack Client (OSC) plugin for Qinling, an OpenStack
+Function as a Service project.
 
-* Client bug tracker
-    * https://launchpad.net/python-qinlingclient
+For more information about Qinling see:
+https://docs.openstack.org/qinling/latest/
 
-* Qinling bug tracker
-    * https://launchpad.net/qinling
+For more information about the OpenStack Client see:
+https://docs.openstack.org/python-openstackclient/latest/
 
-License
--------
+* Free software: Apache license
+* Documentation: https://docs.openstack.org/python-qinlingclient/latest/
+* Source: http://git.openstack.org/cgit/openstack/python-qinlingclient
+* Bugs: https://storyboard.openstack.org/#!/project/926
 
-Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0
+Getting Started
+===============
+
+.. note:: This is an OpenStack Client plugin.  The ``python-openstackclient``
+          project should be installed to use this plugin.
+
+Qinling client can be installed from PyPI using pip::
+
+    pip install python-qinlingclient
+
+If you want to make changes to the Qinling client for testing and contribution,
+make any changes and then run::
+
+    python setup.py develop
+
+or::
+
+    pip install -e .

doc/requirements.txt

@@ -0,0 +1,7 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+
+sphinx>=1.6.2,!=1.6.6  # BSD
+openstackdocstheme>=1.18.1  # Apache-2.0
+reno>=2.5.0  # Apache-2.0

doc/source/_theme/theme.conf

@@ -1,2 +0,0 @@
-[theme]
-inherit = default

doc/source/cli/index.rst

@@ -0,0 +1 @@
+.. include:: osc/v1/qinling.rst

doc/source/cli/osc/v1/qinling.rst

@@ -0,0 +1,37 @@
+Using Qinling CLI extensions to OpenStack Client
+================================================
+
+=======
+runtime
+=======
+
+.. autoprogram-cliff:: openstack.function_engine.v1
+    :command: runtime *
+
+========
+function
+========
+
+.. autoprogram-cliff:: openstack.function_engine.v1
+    :command: function *
+
+==================
+function execution
+==================
+
+.. autoprogram-cliff:: openstack.function_engine.v1
+    :command: function execution *
+
+===
+job
+===
+
+.. autoprogram-cliff:: openstack.function_engine.v1
+    :command: job *
+
+=======
+webhook
+=======
+
+.. autoprogram-cliff:: openstack.function_engine.v1
+    :command: webhook *

doc/source/conf.py

@@ -1,41 +1,35 @@
 # -*- 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
+# 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
 #
-#       http://www.apache.org/licenses/LICENSE-2.0
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#  License for the specific language governing permissions and limitations
-#  under the License.
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
 import os
+import sys
 
-project = 'python-qinlingclient'
-
+sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.intersphinx',
-              'sphinx.ext.coverage',
-              'sphinx.ext.ifconfig',
-              'sphinx.ext.graphviz']
+extensions = [
+    'sphinx.ext.autodoc',
+    'openstackdocstheme',
+    'cliff.sphinxext'
+]
 
 # 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
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = []
-if os.getenv('HUDSON_PUBLISH_DOCS'):
-    templates_path = ['_ga', '_templates']
-else:
-    templates_path = ['_templates']
-
 # The suffix of source filenames.
 source_suffix = '.rst'
 
@@ -43,8 +37,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-copyright = u'Catalyst IT, Inc'
-exclude_trees = ['api']
+project = u'python-qinlingclient'
+copyright = u'2016, OpenStack Foundation'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -60,24 +54,32 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+# html_theme_path = ["."]
+# html_theme = '_theme'
+# html_static_path = ['static']
+
+html_theme = 'openstackdocs'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
 latex_documents = [
-    (
-        'index',
-        '%s.tex' % project,
-        u'%s Documentation' % project,
-        u'Catalyst IT, Inc',
-        'manual'
-    ),
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'OpenStack Foundation', 'manual'),
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+#intersphinx_mapping = {'http://docs.python.org/': None}
+
+# openstackdocstheme options
+repository_name = 'openstack/python-qinlingclient'
+bug_project = 'qinling'
+bug_tag = 'doc'
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+autoprogram_cliff_application = 'openstack'

doc/source/contributor/index.rst

@@ -0,0 +1,4 @@
+============
+Contributing
+============
+.. include:: ../../../CONTRIBUTING.rst

doc/source/index.rst

@@ -1,27 +1,34 @@
-..
-      Copyright 2017 Catalyst IT Limited
+.. python-qinlingclient documentation master file, created by
+   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
-      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
+Python Qinling Client
+=====================
 
-           http://www.apache.org/licenses/LICENSE-2.0
+The Python Qinling Client (python-qinlingclient) is a command-line client for
+the OpenStack Function as a Service.
 
-      Unless required by applicable law or agreed to in writing, software
-      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-      License for the specific language governing permissions and limitations
-      under the License.
+Getting Started
+---------------
 
-==================
-Qinling API Client
-==================
+.. toctree::
+   :maxdepth: 2
 
-In order to use the python api directly, you must first obtain an auth token
-and identify which endpoint you wish to speak to. Once you have done so,
-you can use the API like so::
+   Project Overview <readme>
+   install/index
+   contributor/index
 
-    >>> from qinlingclient import Client
-    >>> qinling = Client('1', endpoint=QINLING_URL, token=OS_AUTH_TOKEN)
-    ...
+Usage
+-----
 
+.. toctree::
+   :maxdepth: 2
+
+   cli/index
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`search`

doc/source/install/index.rst

@@ -0,0 +1,17 @@
+============
+Installation
+============
+
+This is an OpenStack Client plugin for the FaaS (Qinling) project.
+
+Install the plugin::
+
+    $ pip install python-qinlingclient
+
+Or, if you have virtualenvwrapper installed::
+
+    $ mkvirtualenv python-qinlingclient
+    $ pip install python-qinlingclient
+
+.. note:: If python-openstackclient is not already installed it will be
+          installed as part of the requirements for the Qinling client plugin.

doc/source/readme.rst

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

requirements.txt

@@ -4,6 +4,7 @@
 pbr!=2.1.0,>=2.0.0 # Apache-2.0
 PrettyTable<0.8,>=0.7.1 # BSD
 python-keystoneclient>=3.8.0 # Apache-2.0
+python-openstackclient>=3.12.0 # Apache-2.0
 iso8601>=0.1.11 # MIT
 six>=1.10.0 # MIT
 Babel!=2.4.0,>=2.3.4 # BSD