Add documentation for python-tackerclient

This patch also fix "InterpreterNotFound: pypy" error in tox.ini

This patch also follow the new PTI for document build [1][2]

[1] https://governance.openstack.org/tc/reference/project-testing-interface.html
[2] http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html

Change-Id: I9fb6637cb95603532b46f89dc4beab185278c833
Closes-bug: #1754556
Closes-bug: #1754926

README.rst

@@ -24,31 +24,45 @@ as stable/<branch> for any stable branch installation. For eg:
 stable/queens, stable/pike. If unspecified the default will be
 master branch.
 
-1. Clone tacker-client repository.
+Using python install
+--------------------
+1. Clone python-tackerclient repository.
 
   ::
 
-    cd ~/
+    $ cd ~/
-    git clone https://github.com/openstack/python-tackerclient -b <branch_name>
+    $ git clone https://github.com/openstack/python-tackerclient -b <branch_name>
 
 
-2. Install tacker-client.
+2. Install python-tackerclient.
 
   ::
 
-    cd python-tackerclient
+    $ cd python-tackerclient
-    sudo python setup.py install
+    $ sudo python setup.py install
 
 
-You can also install the latest version by using following command:
+Using pip
+---------
+
+You can also install the latest version by using ``pip`` command:
 
   ::
 
-    pip install python-tackerclient
+    $ pip install python-tackerclient
+
+
+Or, if it is needed to install ``python-tackerclient`` from master branch,
+type
+
+  ::
+
+    $ pip install git+https://github.com/openstack/python-tackerclient.git
 
 
 More Information
 ================
 
-[1] Tacker Documentation: https://docs.openstack.org/tacker/
+* Python-tackerclient documentation: https://docs.openstack.org/python-tackerclient/
-[2] Tacker Wiki: https://wiki.openstack.org/wiki/Tacker
+* Tacker Documentation: https://docs.openstack.org/tacker/
+* Tacker Wiki: https://wiki.openstack.org/wiki/Tacker

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.
+# These are needed for docs generation
+sphinx!=1.6.6,<1.7.0,>=1.6.2 # BSD
+openstackdocstheme>=1.18.1 # Apache-2.0
+reno>=2.5.0 # Apache-2.0

doc/source/cli/index.rst

@@ -11,7 +11,6 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-
       Convention for heading levels in Neutron devref:
       =======  Heading 0 (reserved for the title in a document)
       -------  Heading 1
@@ -21,20 +20,233 @@
       (Avoid deeper levels because they do not render well.)
 
 =========
-Using CLI
+CLI Usage
 =========
 
-There are two CLIs which support the Networking API:
+There are two CLIs which support the Tacker API:
 `OpenStackClient (OSC)
 <https://docs.openstack.org/python-openstackclient/latest/>`__
-and :doc:`neutron CLI <neutron>` (deprecated).
+and `tacker CLI <tacker>`.
 
-OpenStackClient
+Tacker CLI
----------------
+----------
 
-#TODO
+.. code-block:: console
+
+    usage: tacker [--version] [-v] [-q] [-h] [-r NUM]
+              [--os-service-type <os-service-type>]
+              [--os-endpoint-type <os-endpoint-type>]
+              [--service-type <service-type>]
+              [--endpoint-type <endpoint-type>]
+              [--os-auth-strategy <auth-strategy>] [--os-auth-url <auth-url>]
+              [--os-tenant-name <auth-tenant-name> | --os-project-name <auth-project-name>]
+              [--os-tenant-id <auth-tenant-id> | --os-project-id <auth-project-id>]
+              [--os-username <auth-username>] [--os-user-id <auth-user-id>]
+              [--os-user-domain-id <auth-user-domain-id>]
+              [--os-user-domain-name <auth-user-domain-name>]
+              [--os-project-domain-id <auth-project-domain-id>]
+              [--os-project-domain-name <auth-project-domain-name>]
+              [--os-cert <certificate>] [--os-cacert <ca-certificate>]
+              [--os-key <key>] [--os-password <auth-password>]
+              [--os-region-name <auth-region-name>] [--os-token <token>]
+              [--http-timeout <seconds>] [--os-url <url>] [--insecure]
+
+    Command-line interface to the Tacker APIs
+
+    optional arguments:
+      --version             show program's version number and exit
+      -v, --verbose, --debug
+                            Increase verbosity of output and show tracebacks on
+                            errors. You can repeat this option.
+      -q, --quiet           Suppress output except warnings and errors.
+      -h, --help            Show this help message and exit.
+      -r NUM, --retries NUM
+                            How many times the request to the Tacker server should
+                            be retried if it fails.
+      --os-service-type <os-service-type>
+                            Defaults to env[OS_TACKER_SERVICE_TYPE] or nfv-
+                            orchestration.
+      --os-endpoint-type <os-endpoint-type>
+                            Defaults to env[OS_ENDPOINT_TYPE] or publicURL.
+      --service-type <service-type>
+                            DEPRECATED! Use --os-service-type.
+      --endpoint-type <endpoint-type>
+                            DEPRECATED! Use --os-endpoint-type.
+      --os-auth-strategy <auth-strategy>
+                            DEPRECATED! Only keystone is supported.
+      --os-auth-url <auth-url>
+                            Authentication URL, defaults to env[OS_AUTH_URL].
+      --os-tenant-name <auth-tenant-name>
+                            Authentication tenant name, defaults to
+                            env[OS_TENANT_NAME].
+      --os-project-name <auth-project-name>
+                            Another way to specify tenant name. This option is
+                            mutually exclusive with --os-tenant-name. Defaults to
+                            env[OS_PROJECT_NAME].
+      --os-tenant-id <auth-tenant-id>
+                            Authentication tenant ID, defaults to
+                            env[OS_TENANT_ID].
+      --os-project-id <auth-project-id>
+                            Another way to specify tenant ID. This option is
+                            mutually exclusive with --os-tenant-id. Defaults to
+                            env[OS_PROJECT_ID].
+      --os-username <auth-username>
+                            Authentication username, defaults to env[OS_USERNAME].
+      --os-user-id <auth-user-id>
+                            Authentication user ID (Env: OS_USER_ID)
+      --os-user-domain-id <auth-user-domain-id>
+                            OpenStack user domain ID. Defaults to
+                            env[OS_USER_DOMAIN_ID].
+      --os-user-domain-name <auth-user-domain-name>
+                            OpenStack user domain name. Defaults to
+                            env[OS_USER_DOMAIN_NAME].
+      --os-project-domain-id <auth-project-domain-id>
+                            Defaults to env[OS_PROJECT_DOMAIN_ID].
+      --os-project-domain-name <auth-project-domain-name>
+                            Defaults to env[OS_PROJECT_DOMAIN_NAME].
+      --os-cert <certificate>
+                            Path of certificate file to use in SSL connection.
+                            This file can optionally be prepended with the private
+                            key. Defaults to env[OS_CERT].
+      --os-cacert <ca-certificate>
+                            Specify a CA bundle file to use in verifying a TLS
+                            (https) server certificate. Defaults to
+                            env[OS_CACERT].
+      --os-key <key>        Path of client key to use in SSL connection. This
+                            option is not necessary if your key is prepended to
+                            your certificate file. Defaults to env[OS_KEY].
+      --os-password <auth-password>
+                            Authentication password, defaults to env[OS_PASSWORD].
+      --os-region-name <auth-region-name>
+                            Authentication region name, defaults to
+                            env[OS_REGION_NAME].
+      --os-token <token>    Authentication token, defaults to env[OS_TOKEN].
+      --http-timeout <seconds>
+                            Timeout in seconds to wait for an HTTP response.
+                            Defaults to env[OS_NETWORK_TIMEOUT] or None if not
+                            specified.
+      --os-url <url>        Defaults to env[OS_URL].
+      --insecure            Explicitly allow tackerclient to perform "insecure"
+                            SSL (https) requests. The server's certificate will
+                            not be verified against any certificate authorities.
+                            This option should be used with caution.
+
+    Commands for API v1.0:
+      bash-completion        Prints all of the commands and options for bash-completion.
+      chain-list             List SFCs that belong to a given tenant.
+      chain-show             Show information of a given SFC.
+      classifier-list        List FCs that belong to a given tenant.
+      classifier-show        Show information of a given FC.
+      cluster-create         Create a Cluster.
+      cluster-delete         Delete a given Cluster.
+      cluster-list           List Clusters that belong to a given tenant.
+      cluster-member-add     Add a new Cluster Member to given Cluster.
+      cluster-member-delete  Delete a given Cluster Member.
+      cluster-member-list    List Cluster Members that belong to a given tenant.
+      cluster-member-show    Show information of a given Cluster Member.
+      cluster-show           Show information of a given Cluster.
+      event-show             Show event given the event id.
+      events-list            List events of resources.
+      ext-list               List all extensions.
+      ext-show               Show information of a given resource.
+      help                   print detailed help for another command
+      nfp-list               List NFPs that belong to a given tenant.
+      nfp-show               Show information of a given NFP.
+      ns-create              Create a NS.
+      ns-delete              Delete given NS(s).
+      ns-list                List NS that belong to a given tenant.
+      ns-show                Show information of a given NS.
+      nsd-create             Create a NSD.
+      nsd-delete             Delete a given NSD.
+      nsd-list               List NSDs that belong to a given tenant.
+      nsd-show               Show information of a given NSD.
+      nsd-template-show      Show template of a given NSD.
+      vim-delete             Delete given VIM(s).
+      vim-events-list        List events of VIMs.
+      vim-list               List VIMs that belong to a given tenant.
+      vim-register           Create a VIM.
+      vim-show               Show information of a given VIM.
+      vim-update             Update a given VIM.
+      vnf-create             Create a VNF.
+      vnf-delete             Delete given VNF(s).
+      vnf-events-list        List events of VNFs.
+      vnf-list               List VNF that belong to a given tenant.
+      vnf-resource-list      List resources of a VNF like VDU, CP, etc.
+      vnf-scale              Scale a VNF.
+      vnf-show               Show information of a given VNF.
+      vnf-update             Update a given VNF.
+      vnfd-create            Create a VNFD.
+      vnfd-delete            Delete given VNFD(s).
+      vnfd-events-list       List events of VNFDs.
+      vnfd-list              List VNFD that belong to a given tenant.
+      vnfd-show              Show information of a given VNFD.
+      vnfd-template-show     Show template of a given VNFD.
+      vnffg-create           Create a VNFFG.
+      vnffg-delete           Delete a given VNFFG.
+      vnffg-list             List VNFFGs that belong to a given tenant.
+      vnffg-show             Show information of a given VNFFG.
+      vnffg-update           Update a given VNFFG.
+      vnffgd-create          Create a VNFFGD.
+      vnffgd-delete          Delete a given VNFFGD.
+      vnffgd-list            List VNFFGDs that belong to a given tenant.
+      vnffgd-show            Show information of a given VNFFGD.
+      vnffgd-template-show   Show template of a given VNFFGD.
+
+
+OpenStackClient CLI
+-------------------
+
+The following list covers the extended commands for Tacker services
+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 vnf create                            Create a VNF.
+   openstack vnf delete                            Delete given VNF(s).
+   openstack vnf list                              List VNF(s) that belong to a given tenant.
+   openstack vnf resource list                     List resources of a VNF like VDU, CP, etc.
+   openstack vnf scale                             Scale a VNF.
+   openstack vnf show                              Show information of a given VNF.
+   openstack vnf set                               Update a given VNF.
+   openstack vnf descriptor create                 Create a VNFD.
+   openstack vnf descriptor delete                 Delete given VNFD(s).
+   openstack vnf descriptor list                   List VNFD(s) that belong to a given tenant.
+   openstack vnf descriptor show                   Show information of a given VNFD.
+   openstack vnf descriptor template show          Show template of a given VNFD.
+   openstack vim list                              List VIM(s) that belong to a given tenant.
+   openstack vim register                          Create a VIM.
+   openstack vim show                              Show information of a given VIM.
+   openstack vim set                               Update a given VIM.
+   openstack vim delete                            Delete given VIM(s).
+   openstack ns create                             Create a NS.
+   openstack ns delete                             Delete given NS(s).
+   openstack ns list                               List NS that belong to a given tenant.
+   openstack ns show                               Show information of a given NS.
+   openstack ns descriptor create                  Create a NSD.
+   openstack ns descriptor delete                  Delete a given NSD.
+   openstack ns descriptor list                    List NSD(s) that belong to a given tenant.
+   openstack ns descriptor show                    Show information of a given NSD.
+   openstack ns descriptor template show           Show template of a given NSD.
+   openstack vnf graph create                      Create a VNFFG.
+   openstack vnf graph delete                      Delete a given VNFFG.
+   openstack vnf graph list                        List VNFFG(s) that belong to a given tenant.
+   openstack vnf graph show                        Show information of a given VNFFG.
+   openstack vnf graph set                         Update a given VNFFG.
+   openstack vnf graph descriptor create           Create a VNFFGD.
+   openstack vnf graph descriptor delete           Delete a given VNFFGD.
+   openstack vnf graph descriptor list             List VNFFGD(s) that belong to a given tenant.
+   openstack vnf graph descriptor show             Show information of a given VNFFGD.
+   openstack vnf graph descriptor template show    Show template of a given VNFFGD.
+   openstack vnf chain list                        List SFC(s) that belong to a given tenant.
+   openstack vnf chain show                        Show information of a given SFC.
+   openstack vnf classifier list                   List FC(s) that belong to a given tenant.
+   openstack vnf classifier show                   Show information of a given FC.
+   openstack vnf network forwarding path list      List NFP(s) that belong to a given tenant.
+   openstack vnf network forwarding path show      Show information of a given NFP.
+   openstack nfv event show                        Show event given the event id.
+   openstack nfv event list                        List events of resources.
 
-neutron CLI
------------
 
-#TODO

doc/source/conf.py

@@ -1,7 +1,29 @@
 # -*- 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
 #
+#      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.
 
-# -- General configuration ---------------------------------------------
+# python-tackerclient documentation build configuration file
+
+import os
+import sys
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#    sys.path.append(os.path.abspath('.'))
+
+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.
@@ -12,12 +34,6 @@ extensions = [
     'cliff.sphinxext',
 ]
 
-# openstackdocstheme options
-repository_name = 'openstack/python-tackerclient'
-bug_project = 'python-tackerclient'
-bug_tag = 'doc'
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -28,7 +44,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-copyright = u'OpenStack Foundation'
+project = 'python-tackerclient'
+copyright = 'OpenStack Contributors'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -40,7 +57,7 @@ add_module_names = True
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# -- Options for HTML output ---------------------------------------------
+# -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
@@ -49,6 +66,19 @@ html_theme = 'openstackdocs'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'tackerclientdoc'
 
-# -- Options for cliff.sphinxext plugin ---------------------------------------
+# 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'
 
-autoprogram_cliff_application = 'openstack'
+# -- Options for manual page output -------------------------------------------
+
+man_pages = [
+    ('cli/index', 'tacker', u'Client for Tacker API',
+     [u'OpenStack Contributors'], 1),
+]
+
+# -- Options for openstackdocstheme -------------------------------------------
+
+repository_name = 'openstack/python-tackerclient'
+bug_project = 'python-tackerclient'
+bug_tag = 'doc'

doc/source/contributor/contributing.rst

@@ -0,0 +1,26 @@
+..
+      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.
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+============
+Contributing
+============
+
+.. include:: ../../../CONTRIBUTING.rst

doc/source/contributor/developing.rst

@@ -0,0 +1,195 @@
+..
+      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.
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+===================================
+Developing with Python-TackerClient
+===================================
+
+Project Info
+============
+
+* **Free software:** under the `Apache license <http://www.apache.org/licenses/LICENSE-2.0>`_
+* **Tacker Service:** http://git.openstack.org/cgit/openstack/tacker
+* **Tacker Client Library:** http://git.openstack.org/cgit/openstack/python-tackerclient
+* **Tacker Service Bugs:** http://bugs.launchpad.net/tacker
+* **Client Bugs:** https://bugs.launchpad.net/python-tackerclient
+* **Blueprints:** https://blueprints.launchpad.net/tacker
+
+Meetings
+========
+For details please refer to the `OpenStack IRC meetings`_ page.
+
+.. _`OpenStack IRC meetings`: http://eavesdrop.openstack.org/#Tacker_(NFV_Orchestrator_and_VNF_Manager)_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 TackerClient.
+
+.. 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.5 and PEP-8), list the
+environments with the ``-e`` option, separated by spaces:
+
+.. code-block:: bash
+
+    $ tox -e py27,py35,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-TackerClient 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

@@ -11,7 +11,6 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-
       Convention for heading levels in Neutron devref:
       =======  Heading 0 (reserved for the title in a document)
       -------  Heading 1
@@ -28,4 +27,10 @@ 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.
 
-#TODO
+.. toctree::
+   :maxdepth: 2
+
+   contributing.rst
+   developing.rst
+
+

doc/source/index.rst

@@ -19,39 +19,38 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-==================================
+=================================
-python-tackerclient documentation
+Python-TackerClient Documentation
-==================================
+=================================
 
-This is a client for OpenStack NFV MANO API. It provides
+This is a client for OpenStack NFV MANO (Tacker) API. It provides
 :doc:`Python API bindings <reference/index>` (the tackerclient module) and
 :doc:`command-line interface (CLI) <cli/index>`.
 
-
+Contents
-User Documentation
+--------
-------------------
 
 .. toctree::
    :maxdepth: 2
 
+   install/index
    cli/index
+   contributor/index
    reference/index
 
-Contributor Guide
------------------
 
-In the :doc:`Contributor Guide <contributor/index>`, you will find
+Release Notes
-information on tackerclient's lower level programming details or APIs
+-------------
-as well as the transition to OpenStack client.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   contributor/index
+   Release Notes <http://docs.openstack.org/releasenotes/python-tackerclient>
 
 
-History
+Indices and Tables
--------
+------------------
 
-Release notes is available at
+* :ref:`genindex`
-http://docs.openstack.org/releasenotes/python-tackerclient/.
+* :ref:`modindex`
+* :ref:`search`

doc/source/install/index.rst

@@ -11,7 +11,6 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-
       Convention for heading levels in Neutron devref:
       =======  Heading 0 (reserved for the title in a document)
       -------  Heading 1
@@ -20,19 +19,51 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-=================
+============
-Install Guide
+Installation
-=================
+============
 
-To install ``python-tackerclient``, it is required to have ``pip``
+**Note:** The paths we are using for configuration files in these steps
-(in most cases). Make sure that ``pip`` is installed. Then type::
+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
+====================
+1. Clone python-tackerclient repository.
+
+  ::
+
+    $ cd ~/
+    $ git clone https://github.com/openstack/python-tackerclient -b <branch_name>
+
+
+2. Install python-tackerclient.
+
+  ::
+
+    $ cd python-tackerclient
+    $ sudo python setup.py install
+
+
+Using pip
+=========
+
+You can also install the latest version by using ``pip`` command:
+
+  ::
 
     $ pip install python-tackerclient
 
+
 Or, if it is needed to install ``python-tackerclient`` from master branch,
-type::
+type
+
+  ::
 
     $ pip install git+https://github.com/openstack/python-tackerclient.git
 
-After ``python-tackerclient`` is installed you will see command ``tacker``
-in your environment.

doc/source/reference/index.rst

@@ -11,7 +11,6 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-
       Convention for heading levels in Neutron devref:
       =======  Heading 0 (reserved for the title in a document)
       -------  Heading 1
@@ -20,10 +19,8 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-tackerclient Python API
+=========
-========================
+Reference
+=========
 
-Basic Usage
+(To be updated)
------------
-
-#TODO

releasenotes/notes/bug-1754556-53268d3081fa18d1.yaml

@@ -0,0 +1,4 @@
+---
+fixes:
+  - |
+    Add documentation for python-tackerclient

releasenotes/notes/bug-1754926-06ac4d7ffd17b5ce.yaml

@@ -0,0 +1,4 @@
+---
+fixes:
+  - |
+    Fix local test fail with InterpreterNotFound: pypy

releasenotes/source/conf.py

@@ -36,9 +36,8 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'oslosphinx',
     'reno.sphinxext',
-    'openstackdocstheme'
+    'openstackdocstheme',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

requirements.txt

@@ -11,7 +11,6 @@ simplejson>=3.5.1 # MIT
 six>=1.10.0 # MIT
 stevedore>=1.20.0 # Apache-2.0
 Babel!=2.4.0,>=2.3.4 # BSD
-
 oslo.i18n>=3.15.3 # Apache-2.0
 osc-lib>=1.8.0 # Apache-2.0
 oslo.log>=3.36.0 # Apache-2.0

setup.cfg

@@ -75,9 +75,14 @@ openstack.tackerclient.v1 =
 
 
 [build_sphinx]
-all_files = 1
+builders = html,man
-build-dir = doc/build
 source-dir = doc/source
+build-dir = doc/build
+all-files = 1
+warning-is-error = 1
+
+[upload_sphinx]
+upload-dir = doc/build/html
 
 [build_releasenotes]
 all_files = 1

test-requirements.txt

@@ -5,12 +5,6 @@ hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
 coverage!=4.4,>=4.0 # Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD
 python-subunit>=1.0.0 # Apache-2.0/BSD
-sphinx!=1.6.6,<1.7.0,>=1.6.2 # BSD
 testrepository>=0.0.18 # Apache-2.0/BSD
 testtools>=2.2.0 # MIT
-oslosphinx>=4.7.0 # Apache-2.0
-openstackdocstheme>=1.18.1 # Apache-2.0
-
-# releasenotes
-reno>=2.5.0 # Apache-2.0
 mock>=2.0.0 # BSD

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py35,py27,pypy,pep8
+envlist = py35,py27,pep8,docs
 minversion = 2.0
 skipsdist = True
 
@@ -24,9 +24,11 @@ distribute = false
 commands = {posargs}
 
 [testenv:docs]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:cover]