Add initial documentation for OSC

This patch creates initial documentation for OSC, with
general plugin information and a few examples.
New commands, that are implemented, should be then
referenced in doc/source/cli/osc/v2/index.rst

Change-Id: I6fa9fcb3cf41a2992a4b5c7b38c54825106e9ce5
Partially-implements: bp openstack-client-support

doc/requirements.txt

@@ -5,3 +5,4 @@ openstackdocstheme>=2.2.1 # Apache-2.0
 sphinx>=2.0.0,!=2.1.0 # BSD
 reno>=3.1.0 # Apache-2.0
 sphinxcontrib-programoutput>=0.11  # BSD
+python-openstackclient>=3.12.0 # Apache-2.0

doc/source/cli/osc/v2/index.rst

@@ -0,0 +1,44 @@
+Command Reference
+=================
+
+List of released CLI commands available in openstack client. These commands
+can be referenced by executing ``openstack help share``.
+
+======
+shares
+======
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share create
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share list
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share show
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share delete
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share set
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share unset
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share resize
+
+==================
+share access rules
+==================
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share access *
+
+===========
+share types
+===========
+
+.. autoprogram-cliff:: openstack.share.v2
+    :command: share type *

doc/source/cli/osc_plugin_cli.rst

@@ -0,0 +1,85 @@
+================================================
+``openstack share`` Command-Line Interface (CLI)
+================================================
+
+.. program:: openstack share
+
+Synopsis
+========
+
+:program:`openstack [options] share` <command> [command-options]
+
+:program:`openstack help share` <command>
+
+
+Description
+===========
+
+The OpenStack Client plugin interacts with the Manila service
+through the ``openstack share`` command line interface (CLI).
+
+To use the CLI, you must provide your OpenStack username, password,
+project, auth endpoint and the share API version.
+You can use configuration options ``--os-username``,
+``--os-password``, ``--os-project-name``, ``--os-auth-url``
+and ``--os-share-api-version``, or set the corresponding
+environment variables::
+
+    export OS_USERNAME=foo
+    export OS_PASSWORD=bar
+    export OS_TENANT_NAME=foobarproject
+    export OS_AUTH_URL=http://...
+    export OS_SHARE_API_VERSION=2.51
+
+
+Getting help
+============
+
+To get a full list of all possible commands, run::
+
+    $ openstack help share
+
+To get detailed help for one command, run::
+
+    $ openstack help share <command>
+
+
+Examples
+========
+
+Get information about the openstack share create command::
+
+    $ openstack help share create
+
+Create one share::
+
+    $ openstack share create NFS 1 --name "myshare"
+
+List shares::
+
+    $ openstack share list
+
+Display a share::
+
+    $ openstack share show myshare
+
+Delete a share::
+
+    $ openstack share delete myshare
+
+Extend a 1gb share to 2gb::
+
+    $ openstack share resize myshare 2
+
+Shrink a 2gb share to 1gb::
+
+    $ openstack share resize myshare 1
+
+
+Command Reference
+=================
+.. toctree::
+   :glob:
+   :maxdepth: 3
+
+   osc/v2/*

doc/source/conf.py

@@ -29,7 +29,10 @@ sys.path.insert(0, ROOT)
 # 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', 'openstackdocstheme', 'sphinxcontrib.programoutput']
+extensions = ['sphinx.ext.autodoc',
+              'openstackdocstheme',
+              'sphinxcontrib.programoutput',
+              'cliff.sphinxext']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/source/index.rst

@@ -11,12 +11,22 @@ Manila API in order to use the manila client.
 
 Command-Line Reference
 ~~~~~~~~~~~~~~~~~~~~~~
+There are two shell implementations supported by python-manilaclient.
+The "manila" client supports full feature parity with the manila API:
 
 .. toctree::
    :maxdepth: 2
 
    user/shell
 
+From version 2.0.0, there is a growing support for the OpenStack client.
+It does not yet have full feature parity with the manila API:
+
+.. toctree::
+   :maxdepth: 1
+
+   cli/osc_plugin_cli
+
 Using the python module
 ~~~~~~~~~~~~~~~~~~~~~~~