From e3b3d7e50c6af4a51dc6f5aa44bb39bd41c2dea8 Mon Sep 17 00:00:00 2001 From: Nguyen Hai Date: Thu, 8 Mar 2018 23:03:28 +0900 Subject: [PATCH] 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 | 34 ++- doc/requirements.txt | 7 + doc/source/cli/index.rst | 232 +++++++++++++++++- doc/source/conf.py | 52 +++- doc/source/contributor/contributing.rst | 26 ++ doc/source/contributor/developing.rst | 195 +++++++++++++++ doc/source/contributor/index.rst | 9 +- doc/source/index.rst | 35 ++- doc/source/install/index.rst | 49 +++- doc/source/reference/index.rst | 11 +- .../notes/bug-1754556-53268d3081fa18d1.yaml | 4 + .../notes/bug-1754926-06ac4d7ffd17b5ce.yaml | 4 + releasenotes/source/conf.py | 3 +- requirements.txt | 1 - setup.cfg | 9 +- test-requirements.txt | 6 - tox.ini | 4 +- 17 files changed, 602 insertions(+), 79 deletions(-) create mode 100644 doc/requirements.txt create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/developing.rst create mode 100644 releasenotes/notes/bug-1754556-53268d3081fa18d1.yaml create mode 100644 releasenotes/notes/bug-1754926-06ac4d7ffd17b5ce.yaml diff --git a/README.rst b/README.rst index e8d5eceb..651150b5 100644 --- a/README.rst +++ b/README.rst @@ -24,31 +24,45 @@ as stable/ 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 ~/ - git clone https://github.com/openstack/python-tackerclient -b + $ cd ~/ + $ git clone https://github.com/openstack/python-tackerclient -b -2. Install tacker-client. +2. Install python-tackerclient. :: - cd python-tackerclient - sudo python setup.py install + $ cd python-tackerclient + $ 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/ -[2] Tacker Wiki: https://wiki.openstack.org/wiki/Tacker \ No newline at end of file +* Python-tackerclient documentation: https://docs.openstack.org/python-tackerclient/ +* Tacker Documentation: https://docs.openstack.org/tacker/ +* Tacker Wiki: https://wiki.openstack.org/wiki/Tacker diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..60e8eb88 --- /dev/null +++ b/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 diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index b18601f2..9d836a6f 100644 --- a/doc/source/cli/index.rst +++ b/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) `__ -and :doc:`neutron CLI ` (deprecated). +and `tacker CLI `. -OpenStackClient ---------------- +Tacker CLI +---------- -#TODO +.. code-block:: console + + usage: tacker [--version] [-v] [-q] [-h] [-r NUM] + [--os-service-type ] + [--os-endpoint-type ] + [--service-type ] + [--endpoint-type ] + [--os-auth-strategy ] [--os-auth-url ] + [--os-tenant-name | --os-project-name ] + [--os-tenant-id | --os-project-id ] + [--os-username ] [--os-user-id ] + [--os-user-domain-id ] + [--os-user-domain-name ] + [--os-project-domain-id ] + [--os-project-domain-name ] + [--os-cert ] [--os-cacert ] + [--os-key ] [--os-password ] + [--os-region-name ] [--os-token ] + [--http-timeout ] [--os-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 + Defaults to env[OS_TACKER_SERVICE_TYPE] or nfv- + orchestration. + --os-endpoint-type + Defaults to env[OS_ENDPOINT_TYPE] or publicURL. + --service-type + DEPRECATED! Use --os-service-type. + --endpoint-type + DEPRECATED! Use --os-endpoint-type. + --os-auth-strategy + DEPRECATED! Only keystone is supported. + --os-auth-url + Authentication URL, defaults to env[OS_AUTH_URL]. + --os-tenant-name + Authentication tenant name, defaults to + env[OS_TENANT_NAME]. + --os-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 + Authentication tenant ID, defaults to + env[OS_TENANT_ID]. + --os-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 + Authentication username, defaults to env[OS_USERNAME]. + --os-user-id + Authentication user ID (Env: OS_USER_ID) + --os-user-domain-id + OpenStack user domain ID. Defaults to + env[OS_USER_DOMAIN_ID]. + --os-user-domain-name + OpenStack user domain name. Defaults to + env[OS_USER_DOMAIN_NAME]. + --os-project-domain-id + Defaults to env[OS_PROJECT_DOMAIN_ID]. + --os-project-domain-name + Defaults to env[OS_PROJECT_DOMAIN_NAME]. + --os-cert + 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 + Specify a CA bundle file to use in verifying a TLS + (https) server certificate. Defaults to + env[OS_CACERT]. + --os-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 + Authentication password, defaults to env[OS_PASSWORD]. + --os-region-name + Authentication region name, defaults to + env[OS_REGION_NAME]. + --os-token Authentication token, defaults to env[OS_TOKEN]. + --http-timeout + Timeout in seconds to wait for an HTTP response. + Defaults to env[OS_NETWORK_TIMEOUT] or None if not + specified. + --os-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 **. + +.. 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 diff --git a/doc/source/conf.py b/doc/source/conf.py index de7bca84..95ad3c9c 100644 --- a/doc/source/conf.py +++ b/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' diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 00000000..fc1e4e63 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/developing.rst b/doc/source/contributor/developing.rst new file mode 100644 index 00000000..f989bd0c --- /dev/null +++ b/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 `_ +* **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 + +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 + diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 29920d0e..5ecc6cfd 100644 --- a/doc/source/contributor/index.rst +++ b/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 + + diff --git a/doc/source/index.rst b/doc/source/index.rst index 601157da..0cd0cd6f 100644 --- a/doc/source/index.rst +++ b/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 ` (the tackerclient module) and :doc:`command-line interface (CLI) `. - -User Documentation ------------------- +Contents +-------- .. toctree:: :maxdepth: 2 + install/index cli/index + contributor/index reference/index -Contributor Guide ------------------ -In the :doc:`Contributor Guide `, you will find -information on tackerclient's lower level programming details or APIs -as well as the transition to OpenStack client. +Release Notes +------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - contributor/index + Release Notes -History -------- +Indices and Tables +------------------ -Release notes is available at -http://docs.openstack.org/releasenotes/python-tackerclient/. +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index ec900f93..718e58b9 100644 --- a/doc/source/install/index.rst +++ b/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`` -(in most cases). Make sure that ``pip`` is installed. Then type:: +**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/ 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 + + +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. diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 4ef3cbfc..c5fcc995 100644 --- a/doc/source/reference/index.rst +++ b/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 ------------ - -#TODO +(To be updated) diff --git a/releasenotes/notes/bug-1754556-53268d3081fa18d1.yaml b/releasenotes/notes/bug-1754556-53268d3081fa18d1.yaml new file mode 100644 index 00000000..614d3d19 --- /dev/null +++ b/releasenotes/notes/bug-1754556-53268d3081fa18d1.yaml @@ -0,0 +1,4 @@ +--- +fixes: + - | + Add documentation for python-tackerclient diff --git a/releasenotes/notes/bug-1754926-06ac4d7ffd17b5ce.yaml b/releasenotes/notes/bug-1754926-06ac4d7ffd17b5ce.yaml new file mode 100644 index 00000000..68c15a39 --- /dev/null +++ b/releasenotes/notes/bug-1754926-06ac4d7ffd17b5ce.yaml @@ -0,0 +1,4 @@ +--- +fixes: + - | + Fix local test fail with InterpreterNotFound: pypy diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index e0266245..fb806177 100644 --- a/releasenotes/source/conf.py +++ b/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. diff --git a/requirements.txt b/requirements.txt index aa1d35e9..621b07f6 100644 --- a/requirements.txt +++ b/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 diff --git a/setup.cfg b/setup.cfg index 38688edd..6a501a30 100644 --- a/setup.cfg +++ b/setup.cfg @@ -75,9 +75,14 @@ openstack.tackerclient.v1 = [build_sphinx] -all_files = 1 -build-dir = doc/build +builders = html,man 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 diff --git a/test-requirements.txt b/test-requirements.txt index 78a86f02..2d9bd108 100644 --- a/test-requirements.txt +++ b/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 diff --git a/tox.ini b/tox.ini index add34820..3f948298 100644 --- a/tox.ini +++ b/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]