Improve moganclient documentation

* Reorganize the structure of client documentation
* Add commands descriptions
* Add contributor guide docs

Change-Id: Ibd4cd2a98e574c3c7606d0bc450de94d48e518e7

doc/source/conf.py

@@ -24,8 +24,10 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
     #'sphinx.ext.intersphinx',
-    'openstackdocstheme'
+    'openstackdocstheme',
+    'cliff.sphinxext',
 ]
 
 # openstackdocstheme options
@@ -47,6 +49,8 @@ master_doc = 'index'
 project = u'python-moganclient'
 copyright = u'2016, OpenStack Foundation'
 
+modindex_common_prefix = ['moganclient.']
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
@@ -64,6 +68,7 @@ pygments_style = 'sphinx'
 # 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
@@ -82,3 +87,9 @@ latex_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+
+autoprogram_cliff_application = 'openstack'
+
+autoprogram_cliff_ignored = [
+    '--help', '--format', '--column', '--max-width', '--fit-width',
+    '--print-empty', '--prefix', '--noindent', '--quote']

doc/source/contributing.rst

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

doc/source/contributor/contributing.rst

@@ -0,0 +1,62 @@
+.. _contributing:
+
+==================================
+Contributing to python-moganclient
+==================================
+
+If you're interested in contributing to the python-moganclient project,
+the following will help get you started.
+
+#openstack-mogan on Freenode IRC Network
+----------------------------------------
+There is a very active chat channel at irc://freenode.net/#openstack-mogan.
+This is usually the best place to ask questions and find your way around.
+IRC stands for Internet Relay Chat and it is a way to chat online in real
+time. You can ask a question and come back later to read the answer in the
+log files. Logs for the #openstack-mogan IRC channel are stored at
+http://eavesdrop.openstack.org/irclogs/%23openstack-mogan/.
+
+Contributor License Agreement
+-----------------------------
+
+.. index::
+   single: license; agreement
+
+In order to contribute to the python-moganclient project, you need to have
+signed OpenStack's contributor's agreement.
+
+.. seealso::
+
+   * https://docs.openstack.org/infra/manual/developers.html
+   * https://wiki.openstack.org/wiki/CLA
+
+LaunchPad Project
+-----------------
+
+Most of the tools used for OpenStack depend on a launchpad.net ID for
+authentication. After signing up for a launchpad account, join the
+"openstack" team to have access to the mailing list and receive
+notifications of important events.
+
+.. seealso::
+
+   * https://launchpad.net
+   * https://launchpad.net/python-moganclient
+   * https://launchpad.net/~openstack
+
+
+Project Hosting Details
+-----------------------
+
+Bug tracker
+    https://launchpad.net/python-moganclient
+
+Mailing list (prefix subjects with ``[mogan]`` for faster responses)
+    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
+
+Code Hosting
+    https://git.openstack.org/cgit/openstack/python-moganclient
+
+Code Review
+    https://review.openstack.org/#/q/status:open+project:openstack/python-moganclient,n,z
+

doc/source/contributor/index.rst

@@ -0,0 +1,8 @@
+============================================
+python-moganclient Contributor Documentation
+============================================
+
+.. toctree::
+
+   contributing
+   testing

doc/source/contributor/testing.rst

@@ -0,0 +1,32 @@
+.. _testing:
+
+=======
+Testing
+=======
+
+Python Guideline Enforcement
+............................
+
+All code has to pass the pep8 style guideline to merge into OpenStack, to
+validate the code against these guidelines you can run::
+
+    $ tox -e pep8
+
+Unit Testing
+............
+
+It is strongly encouraged to run the unit tests locally under one or more
+test environments prior to submitting a patch. To run all the recommended
+environments sequentially and pep8 style guideline run::
+
+    $ tox
+
+You can also selectively pick specific test environments by listing your
+chosen environments after a -e flag::
+
+    $ tox -e py35,py27,pep8,pypy
+
+.. note::
+  Tox sets up virtual environment and installs all necessary dependencies.
+  Sharing the environment with devstack testing is not recommended due to
+  conflicting configuration with system dependencies.

doc/source/index.rst

@@ -1,25 +1,26 @@
-.. python-moganclient documentation master file, created by
+==========================================
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+Python Bindings to the OpenStack Mogan API
-   You can adapt this file completely to your liking, but it should at least
+==========================================
-   contain the root `toctree` directive.
 
-Welcome to python-moganclient's documentation!
+This is a client for OpenStack `Mogan`_ API. There's a Python API
-==============================================
+(the `moganclient` modules), and a set of event related commands
+which are integrated with the OSC CLI tool. Each implements the entire Mogan
+API.
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
-   usage
+   contributor/index
-   contributing
+   osc/index
+
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 
+.. _Mogan: https://wiki.openstack.org/wiki/Mogan

doc/source/osc/index.rst

@@ -0,0 +1,7 @@
+=====================================
+python-moganclient User Documentation
+=====================================
+
+.. toctree::
+
+   osc_plugin_cli

doc/source/osc/osc_plugin_cli.rst

@@ -0,0 +1,87 @@
+=============================================
+OpenStack Client Command-Line Interface (CLI)
+=============================================
+
+.. program:: openstack baremetalcompute
+.. highlight:: bash
+
+Synopsis
+========
+
+:program:`openstack [options] baremetalcompute` <command> [command-options]
+
+:program:`openstack help baremetalcompute` <command>
+
+
+Description
+===========
+
+The OpenStack Client plugin interacts with the Bare Metal service
+through the ``openstack baremetalcompute`` command line interface (CLI).
+
+To use ``openstack`` CLI, the OpenStackClient should be installed::
+
+    # pip install python-openstackclient
+
+To use the CLI, you must provide your OpenStack username, password,
+project, and auth endpoint. You can use configuration options
+``--os-username``, ``--os-password``, ``--os-project-id``
+(or ``--os-project-name``), and ``--os-auth-url``,
+or set the corresponding environment variables::
+
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_PROJECT_NAME=project                         # or OS_PROJECT_ID
+    $ export OS_PROJECT_DOMAIN_ID=default
+    $ export OS_USER_DOMAIN_ID=default
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://auth.example.com:5000/identity
+
+This CLI is provided by python-openstackclient and osc-lib projects:
+
+* https://git.openstack.org/openstack/python-openstackclient
+* https://git.openstack.org/openstack/osc-lib
+
+
+Getting help
+============
+
+To get a list of available (sub)commands and options, run::
+
+    $ openstack help baremetalcompute
+
+To get usage and options of a command, run::
+
+    $ openstack help baremetalcompute <sub-command>
+
+
+Examples
+========
+
+Get information about the openstack baremetalcompute server create command::
+
+    $ openstack help baremetalcompute server create
+
+Get a list of baremetalcompute flavors::
+
+    $ openstack baremetalcompute flavor list
+
+Boot a Bare metal server::
+
+    $ openstack baremetalcompute server create --flavor <FLAVOR> --image <IMAGE> --nic net-id=<NETWORK> test
+
+Get a list of baremetal nodes aggregates::
+
+    $ openstack baremetalcompute aggregate list
+
+Command Reference
+=================
+
+List of released CLI commands available in openstack client. These commands
+can be referenced by doing ``openstack help baremetalcompute``.
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   v1/index

doc/source/osc/v1/index.rst

@@ -0,0 +1,103 @@
+
+=======================
+Baremetalcompute server
+=======================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server create
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server show
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server list
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server delete
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server add floating ip
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server add interface
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server lock
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server netinfo
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server reboot
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server remove floating ip
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server remove interface
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server set
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server start
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server stop
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server unlock
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server unset
+
+=============================
+Baremetalcompute server group
+=============================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server group create
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server group show
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server group list
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute server group delete
+
+=======================
+BaremetalCompute flavor
+=======================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute flavor *
+
+==========================
+BaremetalCompute aggregate
+==========================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute aggregate *
+
+========================
+BaremetalCompute keypair
+========================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute keypair *
+
+=====================
+BaremetalCompute node
+=====================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute node *
+
+==================================
+BaremetalCompute availability zone
+==================================
+
+.. autoprogram-cliff:: openstack.baremetal_compute.v1
+    :command: baremetalcompute availability zone *

doc/source/readme.rst

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

doc/source/usage.rst

@@ -1,7 +0,0 @@
-=====
-Usage
-=====
-
-To use python-moganclient in a project::
-
-    import moganclient