Update operator guide documentation

Updated operator guide documentation for
1. added indexing to list sections appropriately
2. populated CLI section using 'cliff.sphinxext' extension
3. removed 'Module Index' section since displaying 404

Change-Id: I17061a1e5456d027a555dc94dc8ac1a6dd802421

doc/source/cli/commands.rst

@@ -0,0 +1,25 @@
+=============
+Command List
+=============
+
+The following list covers the extended commands for Masakari service
+available in **openstack** command.
+
+These commands can be referenced by doing **openstack help** and the detail
+of individual command can be referred by **openstack help <command-name>**.
+
+.. code-block:: console
+
+   openstack segment create                        Create failover segment.
+   openstack segment update                        Update failover segment.
+   openstack segment list                          List all failover segments.
+   openstack segment show                          Show requested failover segment.
+   openstack segment delete                        Delete failover segment.
+   openstack segment host create                   Create host for given failover segment.
+   openstack segment host update                   Update Create host for given failover segment.
+   openstack segment host list                     List all hosts associated to failover segment.
+   openstack segment host show                     Show Create host for given failover segment.
+   openstack segment host delete                   Delete Create host for given failover segment.
+   openstack notification create                   Create notification of host.
+   openstack notification list                     List notifications of host.
+   openstack notification show                     List notification of host.

doc/source/cli/index.rst

@@ -0,0 +1,9 @@
+============
+CLI Usage
+============
+
+.. toctree::
+   :glob:
+   :maxdepth: 3
+
+   *

doc/source/cli/masakari_commands.rst

@@ -0,0 +1,8 @@
+=================
+Masakari commands
+=================
+
+Masakari commands are CLI interface.
+
+.. autoprogram-cliff:: openstack.ha.v1
+   :command: *

doc/source/conf.py

@@ -22,7 +22,8 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'openstackdocstheme',
-    'sphinx.ext.autodoc'
+    'sphinx.ext.autodoc',
+    'cliff.sphinxext',
     #'sphinx.ext.intersphinx',
 ]
 
@@ -80,3 +81,5 @@ repository_name = 'openstack/python-masakariclient'
 bug_project = 'python-masakariclient'
 bug_tag = ''
 
+# -- Options for cliff.sphinxext plugin ---------------------------------------
+autoprogram_cliff_application = 'openstack'

doc/source/contributing.rst

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

doc/source/contributor/contributing.rst

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

doc/source/contributor/developing.rst

@@ -0,0 +1,174 @@
+=====================================
+Developing with Python-masakariClient
+=====================================
+
+Project Info
+============
+
+* **Free software:** under the `Apache license <http://www.apache.org/licenses/LICENSE-2.0>`_
+* **masakari Service:** https://opendev.org/openstack/masakari
+* **Masakari Client Library:** https://opendev.org/openstack/python-masakariclient
+* **masakari Service Bugs:** https://bugs.launchpad.net/masakari
+* **Client Bugs:** https://bugs.launchpad.net/python-masakariclient
+* **Blueprints:** https://blueprints.launchpad.net/masakari
+
+Meetings
+========
+For details please refer to the `OpenStack IRC meetings`_ page.
+
+.. _`OpenStack IRC meetings`: http://eavesdrop.openstack.org/#Masakari_Team_Meeting
+
+Testing
+=======
+
+Install the prerequisites for Tox:
+
+* On Ubuntu or Debian:
+
+  .. code-block:: bash
+
+    $ apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \
+      zlib1g-dev
+
+  You may need to use pip install for some packages.
+
+
+* On RHEL or CentOS including Fedora:
+
+  .. code-block:: bash
+
+    $ yum install gcc python-devel libxml2-devel libxslt-devel
+
+* On openSUSE or SUSE linux Enterprise:
+
+  .. code-block:: bash
+
+    $ zypper install gcc python-devel libxml2-devel libxslt-devel
+
+Install python-tox:
+
+.. code-block:: bash
+
+    $ pip install tox
+
+To run the full suite of tests maintained within Masakariclient.
+
+.. code-block:: bash
+
+    $ tox
+
+.. NOTE::
+
+    The first time you run ``tox``, it will take additional time to build
+    virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
+    your virtualenv in a similar manner.
+
+
+To run tests for one or more specific test environments(for example, the
+most common configuration of Python 2.7, Python 3.6, Python 3.7 and PEP-8),
+list the environments with the ``-e`` option, separated by spaces:
+
+.. code-block:: bash
+
+    $ tox -e py27,py36,py37,pep8
+
+See ``tox.ini`` for the full list of available test environments.
+
+Building the Documentation
+==========================
+
+The documentation is generated with Sphinx using the ``tox`` command. To
+create HTML docs, run the commands:
+
+.. code-block:: bash
+
+    $ tox -e docs
+
+The resultant HTML will be in the ``doc/build/html`` directory.
+
+Release Notes
+=============
+
+The release notes for a patch should be included in the patch.  See the
+`Project Team Guide`_ for more information on using reno in OpenStack.
+
+.. _`Project Team Guide`: http://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes
+
+If any of the following applies to the patch, a release note is required:
+
+* The deployer needs to take an action when upgrading
+* The plugin interface changes
+* A new feature is implemented
+* A command or option is removed
+* Current behavior is changed
+* A security bug is fixed
+
+Reno is used to generate release notes. Use the commands:
+
+.. code-block:: bash
+
+    $ tox -e venv -- reno new <bug-,bp-,whatever>
+
+Then edit the sample file that was created and push it with your change.
+
+To run the commands and see results:
+
+.. code-block:: bash
+
+    $ git commit  # Commit the change because reno scans git log.
+
+    $ tox -e releasenotes
+
+At last, look at the generated release notes
+files in ``releasenotes/build/html`` in your browser.
+
+Testing new code
+================
+
+If a developer wants to test new code (feature, command or option) that
+they have written, Python-masakariclient may be installed from source by running
+the following commands in the base directory of the project:
+
+.. code-block:: bash
+
+   $ python setup.py install
+
+or
+
+.. code-block:: bash
+
+   $ pip install -e .
+
+Standardize Import Format
+=========================
+
+.. _`Import Order Guide`: https://docs.openstack.org/hacking/latest/user/hacking.html#imports
+
+The import order shows below:
+
+* {{stdlib imports in human alphabetical order}}
+* \n
+* {{third-party lib imports in human alphabetical order}}
+* \n
+* {{project imports in human alphabetical order}}
+* \n
+* \n
+* {{begin your code}}
+
+Example
+~~~~~~~
+
+.. code-block:: python
+
+    import copy
+    import fixtures
+    import mock
+    import os
+
+    from osc_lib.api import auth
+    from osc_lib import utils
+    import six
+
+    from openstackclient import shell
+    from openstackclient.tests import utils
+

doc/source/contributor/index.rst

@@ -0,0 +1,13 @@
+=================
+Contributor Guide
+=================
+
+In the Contributor Guide, you will find information on tackerclient's
+lower level programming details or APIs as well as the transition to
+OpenStack client.
+
+.. toctree::
+   :maxdepth: 2
+
+   contributing.rst
+   developing.rst

doc/source/index.rst

@@ -3,23 +3,32 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+=================================================
 Welcome to python-masakariclient's documentation!
 =================================================
 
-Contents:
+Masakariclient is a command-line client for Masakari.
+
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
-   usage
-   contributing
+   install/index
+   cli/index
+   contributor/index
 
-Indices and tables
+Release Notes
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   Release Notes <https://docs.openstack.org/releasenotes/python-masakariclient/>
+
+Indices and Tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-

doc/source/install/index.rst

@@ -0,0 +1,36 @@
+============
+Installation
+============
+
+**Note:** The paths we are using for configuration files in these steps
+are with reference to Ubuntu Operating System. The paths may vary for
+other Operating Systems.
+
+The branch_name which is used in commands, specify the branch_name
+as stable/<branch> for any stable branch installation. For eg:
+stable/queens, stable/pike. If unspecified the default will be
+master branch.
+
+Using python install
+====================
+Clone and install python-masakariclient repository.::
+
+    $ cd ~/
+    $ git clone https://github.com/openstack/python-masakariclient -b <branch_name>
+    $ cd python-masakariclient
+    $ sudo python setup.py install
+
+
+Using pip
+=========
+
+You can also install the latest version by using ``pip`` command:::
+
+    $ pip install python-masakariclient
+
+
+Or, if it is needed to install ``python-masakariclient`` from master branch,
+type::
+
+    $ pip install git+https://github.com/openstack/python-masakariclient.git
+

doc/source/installation.rst

@@ -1,12 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
-    $ pip install python-masakariclient
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv python-masakariclient
-    $ pip install python-masakariclient

doc/source/readme.rst

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

doc/source/usage.rst

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

tox.ini

@@ -58,7 +58,8 @@ commands =
 
 [testenv:docs]
 basepython = python3
-commands = python setup.py build_sphinx
+commands =
+  sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
 basepython = python3