Enable client documentation

Commit enables following flavours of client's documentation:
- docs: featuring mainly CLI and Python API
- releasenotes: containing all releases releasenotes

Story: 2001058
Task: 5722

Needed-By: Ie064df6f64ee168ad3b5d2dda949b1d14fa7b9d8
Change-Id: I1b0fa11160d8d7d928b4cfbe358ca8c75ed8dd08

.gitignore

@@ -8,9 +8,10 @@ dist
 run_tests.err.log
 .tox
 doc/source/api
-*.egg
+doc/build/
+releasenotes/build/
+*.egg*
 monclient/versioninfo
-*.egg-info
 *.log
 .testrepository
 .pydevproject

doc/source/cli/index.rst

@@ -0,0 +1,13 @@
+=========
+Using CLI
+=========
+
+monasca CLI
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   monasca CLI guide <monasca>
+   monasca CLI formatting <monasca-formatting>
+   monasca CLI debugging <monasca-debug>

doc/source/cli/monasca-debug.rst

@@ -0,0 +1,12 @@
+=========
+Debugging
+=========
+
+``-v`` (or ``--verbose``), as well as  ``--debug``, option can be used
+to increase amount of low-level details regarding all the steps that
+client takes in order to execute the CLI command.
+
+While ``--verbose`` does not dramatically increase the output by displaying
+only basic information about the the execution, ``--debug`` can be used
+to additionally display low-level interactions **monascaclient** make with
+**keystone** server and/or **monasca** server.

doc/source/cli/monasca-formatting.rst

@@ -0,0 +1,36 @@
+===================
+Changing formatting
+===================
+
+Changing displayed columns
+--------------------------
+
+If you want displayed columns in a list operation, ``-c`` option can be used.
+``-c`` can be specified multiple times and the column order will be same as
+the order of ``-c`` options.
+
+Changing format
+---------------
+
+If you want to change the format data is displayed in, you can use ``-f``
+option for that. Format can be specified just once and it affects they way
+the data is printed to the ``STDOUT``. The available formats, data can be
+presented in, can be checked with:
+
+.. code-block:: text
+
+    monasca <command> --help
+
+Look for section **output formatters** and the flag ``--format`` or ``-f``.
+In most of the cases you will be able to pick one out of
+``csv``, ``json``, ``table``, ``value``, ``yaml``.
+
+Affecting the width
+-------------------
+
+If, for some reason, you are not happy with the width the output has taken, you
+can use ```--max-width {number}``` flag and set the value to
+match your preference. Without that output will not be constrained
+by the terminal width. Alternatively you may want to pass ``--fit-width``
+to fit the output to display width. Remember that these flags
+affect the output only if ``table`` formatter is used.

doc/source/cli/monasca.rst

@@ -0,0 +1,92 @@
+=================
+Using monasca CLI
+=================
+
+The **monasca** shell utility interacts with OpenStack Monitoring API from the
+command-line. It supports the entire features of OpenStack Monitoring API.
+
+Basic Usage
+-----------
+
+In order to use the CLI, you must provide your OpenStack username, password,
+project, domain information 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_USERNAME=mini-mon
+    export OS_PASSWORD=password
+    export OS_PROJECT_NAME=mini-mon
+    export OS_USER_DOMAIN_ID=default
+    export OS_PROJECT_DOMAIN_ID=default
+    export OS_AUTH_URL=http://keystone:5000/v3
+
+If you are using Identity v2.0 API (DEPRECATED), you don't need to pass domain
+information.
+
+.. code-block:: shell
+
+    export OS_USERNAME=mini-mon
+    export OS_PASSWORD=password
+    export OS_TENANT_NAME=mini-mon
+    export OS_AUTH_URL=http://keystone:5000/v2.0
+
+Once you've configured your authentication parameters, you can run **monasca**
+commands.  All commands take the form of:
+
+.. code-block:: text
+
+    monasca <command> [arguments...]
+
+Run **monasca help** to get a full list of all possible commands, and run
+**monasca help <command>** to get detailed help for that command.
+
+Using with os-client-config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`os-client-config <https://docs.openstack.org/os-client-config/latest/>`_
+provides more convenient way to manage a collection of client configurations
+and you can easily switch multiple OpenStack-based configurations.
+
+To use os-client-config, you first need to prepare
+``~/.config/openstack/clouds.yaml`` like the following.
+
+.. code-block:: yaml
+
+    clouds:
+      monitoring:
+        auth:
+          auth_url: http://keystone:5000
+          password: password
+          project_domain_id: default
+          project_name: mini-mon
+          user_domain_id: default
+          username: mini-mon
+        identity_api_version: '3'
+        region_name: RegionOne
+
+Then, you need to specify a configuration name defined in the above
+clouds.yaml.
+
+.. code-block:: shell
+
+    export OS_CLOUD=monitoring
+
+For more detail information, see the
+`os-client-config <https://docs.openstack.org/os-client-config/latest/>`_
+documentation.
+
+Using with keystone token
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The command-line tool will attempt to re-authenticate using your provided
+credentials for every request. You can override this behavior by manually
+supplying an auth token using ``--os-url`` and ``--os-auth-token``. You can
+alternatively set these environment variables.
+
+.. code-block:: shell
+
+    export OS_URL=http://monasca.example.org:8070/
+    export OS_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155

doc/source/conf.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+
+from monascaclient.version import version_info
+
+sys.path = [
+    os.path.abspath('../..'),
+    os.path.abspath('../../bin')
+] + sys.path
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '1.6'
+
+# 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.coverage',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.viewcode',
+    'openstackdocstheme'
+]
+
+# geeneral information about project
+repository_name = u'openstack/python-monascaclient'
+project = u'Monasca Client Dev Docs'
+version = version_info.canonical_version_string()
+release = version_info.version_string_with_vcs()
+bug_project = u'880'
+bug_tag = u''
+copyright = u'2014-present, OpenStack Foundation'
+author = u'OpenStack Foundation'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = [
+    'common',
+    'doc',
+    'documentation',
+    'etc',
+    'java'
+]
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+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
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'openstackdocs'
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+# If false, no index is generated.
+html_use_index = True
+
+# If false, no module index is generated.
+html_use_modindex = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'python-monascaclientdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  (master_doc, 'python-monascaclient.tex', u'python-monascaclient Documentation',
+   u'Openstack Foundation \\textless{}monasca@lists.launchpad.net\\textgreater{}', 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'python-monascaclient', u'python-monascaclient Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  (master_doc, 'python-monascaclient', u'python-monascaclient Documentation',
+   author, 'python-monascaclient', 'Rest-API to collect logs from your cloud.',
+   'Miscellaneous'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'https://doc.python.org/': None}

doc/source/index.rst

@@ -0,0 +1,46 @@
+..
+      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
+
+      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.
+
+==================================
+python-monascaclient documentation
+==================================
+
+This is a client for OpenStack Monitoring API. It provides
+:doc:`Python API bindings <reference/index>` (the monascaclient module) and
+:doc:`command-line interface (CLI) <cli/index>`.
+
+User Documentation
+------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   cli/index
+   reference/index
+
+Usage
+-----
+
+In the :doc:`Usage <usage/index>`, you will find
+information on possible ways to use python-monascaclient.
+
+.. toctree::
+   :maxdepth: 2
+
+   usage/index
+
+History
+-------
+
+Release notes is available at
+http://docs.openstack.org/releasenotes/python-monascaclient/.

doc/source/reference/index.rst

@@ -0,0 +1,107 @@
+================
+Using Python API
+================
+
+Python bindings to the OpenStack Monasca API
+============================================
+
+This is a client for the OpenStack Monasca API. It includes a Python
+API (the :mod:`monascaclient` module) and a command-line script
+(installed as :program:`monasca`).
+
+Python API
+==========
+
+To use python-monascaclient in a project, you need to create a client instance
+first. There are couple ways of doing this properly.
+
+With session
+------------
+
+A pseudo-code would be similar to this::
+
+  from keystoneauth1 import identity
+  from keystoneauth1 import session
+  from monascaclient import client
+
+  auth = identity.Password(
+    auth_url='http://my.keystone.com:5000/v3',
+    username='mini-mon',
+    password='password',
+    project_name='mini-mon',
+    user_domain_id='default',
+    project_domain_id='default'
+  )
+  sess = session.Session(auth=auth)
+
+  endpoint = 'http://monasca:8070/'
+  api_version = '2_0'
+
+  c = client.Client(
+    api_version=api_version,
+    endpoint=endpoint,
+    session=session
+  )
+
+  c.alarms.list()
+
+For more information on keystoneauth API, see `Using Sessions`_. We also
+suggest taking closer look at `Keystone Auth Plugins`_. Each of the plugin
+can be used to properly instantiate new session and pass it into the client.
+
+  .. note:: This is recommended way to setup a client.
+     Other cases, described below, create sessions internally.
+
+
+Without session
+---------------
+
+If you do not want to use a session or simply prefer client to instantiate
+one on its own, there are two supported ways
+
+With token
+~~~~~~~~~~
+
+A pseudo-code would be similar to this::
+
+  from monascaclient import client
+
+  c = client.Client(
+    api_version='2_0',
+    endpoint='http://monasca:8070/',
+    token='3bcc3d3a03f44e3d8377f9247b0ad155',
+    project_name='mini-mon',
+    auth_url='http://my.keystone.com:5000/v3'
+  )
+
+  c.alarms.list()
+
+
+With username & password
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A pseudo-code would be similar to this::
+
+  from monascaclient import client
+
+  c = client.Client(
+    api_version='2_0',
+    endpoint='http://monasca:8070/',
+    username='mini-mon',
+    password='password',
+    project_name='mini-mon',
+    auth_url='http://my.keystone.com:5000/v3'
+  )
+
+  c.alarms.list()
+
+Examples
+========
+
+* `Monasca Agent Example`_ - with session
+* `Monasca UI Example`_ - with token
+
+.. _Monasca Agent Example: https://github.com/openstack/monasca-agent/blob/master/monasca_agent/forwarder/api/monasca_api.py
+.. _Monasca UI Example: https://github.com/openstack/monasca-ui/blob/master/monitoring/api/client.py
+.. _Using Sessions: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
+.. _Keystone Auth Plugins: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html

doc/source/usage/index.rst

@@ -0,0 +1,21 @@
+=====
+Usage
+=====
+
+Devstack
+--------
+
+python-monascaclient is bundled inside `Monasca API Devstack Plugin`_ and is
+available right after the devstack finished stacking up. It is always built
+from the **master** branch, unless specified otherwise.
+
+Docker
+------
+
+The client is also part of `monasca-docker`_, a community effort to put
+**monasca** into containers. The image is available as **monasca/client** and
+can be used as drop-in replacement for traditional way of
+deploying the clients.
+
+.. _Monasca API Devstack Plugin: https://github.com/openstack/monasca-api/tree/master/devstack
+.. _monasca-docker: https://github.com/monasca/monasca-docker/tree/master/monasca-client

releasenotes/notes/openstack_docs-5cfec48411370070.yaml

@@ -0,0 +1,11 @@
+---
+prelude: >
+    Documentation done right by Openstack process.
+issues:
+  - |
+    Removed the case where command documentation (held previously in markdown)
+    is out-of-sync with the command itself.
+upgrade:
+  - |
+    Added details about using the CLI variant. Documented the usage
+    of Python API.

releasenotes/source/conf.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '1.6'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'openstackdocstheme',
+    'reno.sphinxext'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+repository_name = u'openstack/python-monascaclient'
+project = u'Monasca Client ReleaseNotes Docs'
+
+# Release notes do not need a version number in the title, they
+# cover multiple releases.
+version = ''
+release = ''
+bug_project = u'880'
+bug_tag = u''
+copyright = u'2014-present, OpenStack Foundation'
+author = u'OpenStack Foundation'
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'openstackdocs'
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MonascaClientReleaseNotesDoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_documents = [(
+     master_doc, 'MonascaClientReleaseNotes.tex',
+     u'Monasca Client Release Notes', [author],
+     'manual'
+)]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'monascaclientreleasenotes',
+     u'Monasca Client Release Notes', [author],
+     1)
+]
+
+# -- Options for Internationalization output ------------------------------
+locale_dirs = ['locale/']

releasenotes/source/index.rst

@@ -0,0 +1,10 @@
+============================
+Monitoring API Release Notes
+============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   unreleased

releasenotes/source/unreleased.rst

@@ -0,0 +1,5 @@
+==============================
+ Current Series Release Notes
+==============================
+
+.. release-notes::

setup.cfg

@@ -4,7 +4,7 @@ summary = Monasca API Client Library
 description-file = README.rst
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
-home-page = https://github.com/openstack/python-monascaclient
+home-page = https://docs.openstack.org/python-monascaclient/latest/
 classifier =
     Environment :: Console
     Intended Audience :: Information Technology
@@ -24,8 +24,21 @@ packages = monascaclient
 console_scripts =
     monasca = monascaclient.shell:main
 
-[pbr]
-autodoc_index_modules = True
+[build_sphinx]
+source-dir = doc/source
+build-dir = doc/build
+all_files = 1
+warning-is-error = 1
+
+[build_releasenotes]
+all_files = 1
+build-dir = releasenotes/build
+source-dir = releasenotes/source
 
 [wheel]
 universal = 1
+
+[egg_info]
+tag_build =
+tag_date = 0
+tag_svn_revision = 0

test-requirements.txt

@@ -4,9 +4,16 @@
 
 hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
 bandit>=1.1.0 # Apache-2.0
+
 coverage!=4.4,>=4.0 # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 os-testr>=1.0.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=1.4.0 # MIT
+
+# documentation
+doc8>=0.6.0 # Apache-2.0
+sphinx>=1.6.2 # BSD
+reno>=2.5.0 # Apache-2.0
+openstackdocstheme>=1.17.0 # Apache-2.0

tox.ini

@@ -9,6 +9,7 @@ setenv =
     BRANCH_NAME=master
     CLIENT_NAME=python-monascaclient
     OS_TEST_PATH=monascaclient/tests
+    PYTHONWARNINGS=default::DeprecationWarning
 passenv = *_proxy
           *_PROXY
 usedevelop = True
@@ -19,8 +20,8 @@ whitelist_externals = bash
                       find
                       rm
 commands =
-  find . -type f -name "*.pyc" -delete
-  rm -Rf .testrepository/times.dbm
+  find {toxinidir} -type f -name "*.pyc" -delete
+  rm -Rf {toxinidir}/.testrepository/times.dbm
 
 [testenv:py27]
 basepython = python2.7
@@ -59,22 +60,55 @@ usedevelop = False
 commands =
   {[testenv:flake8]commands}
   {[testenv:bandit]commands}
+  {[testenv:checkniceness]commands}
 
 [testenv:flake8]
 skip_install = True
 usedevelop = False
 commands =
-    flake8 monascaclient
+  {[testenv]commands}
+  flake8 monascaclient
 
 [testenv:bandit]
 skip_install = True
 usedevelop = False
 commands =
+  {[testenv]commands}
   bandit -r monascaclient -n5 -x {env:OS_TEST_PATH}
 
+[testenv:docs]
+description = Builds full monascaclient documentation
+commands =
+  {[testenv]commands}
+  {[testenv:devdocs]commands}
+  {[testenv:releasenotes]commands}
+
+[testenv:devdocs]
+description = Builds developer documentation
+commands =
+  rm -rf {toxinidir}/doc/build {toxinidir}/doc/source/contributor/api
+  python setup.py build_sphinx
+
+[testenv:releasenotes]
+description = Called from CI script to test and publish the Release Notes
+commands =
+  rm -rf releasenotes/build
+  sphinx-build -a -E -d {toxinidir}/releasenotes/build/doctrees -b html {toxinidir}/releasenotes/source {toxinidir}/releasenotes/build/html
+
+[testenv:checkniceness]
+description = Validates (pep-like) documenation
+commands =
+  {[testenv]commands}
+  doc8 --file-encoding utf-8 {toxinidir}/doc
+  doc8 --file-encoding utf-8 {toxinidir}/releasenotes
+
 [testenv:venv]
 commands = {posargs}
 
+[hacking]
+import_exceptions =
+  six.moves
+
 [flake8]
 show-source = True
 max-line-length = 120