diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 00000000..b18601f2 --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,40 @@ +.. + 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.) + +========= +Using CLI +========= + +There are two CLIs which support the Networking API: +`OpenStackClient (OSC) +`__ +and :doc:`neutron CLI ` (deprecated). + +OpenStackClient +--------------- + +#TODO + +neutron CLI +----------- + +#TODO diff --git a/doc/source/conf.py b/doc/source/conf.py index 4ca6871c..de7bca84 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,14 +1,23 @@ -project = 'python-tackerclient' +# -*- coding: utf-8 -*- +# # -- 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. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'openstackdocstheme' +extensions = [ + 'sphinx.ext.autodoc', + 'reno.sphinxext', + 'openstackdocstheme', + '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'] @@ -38,29 +47,8 @@ pygments_style = 'sphinx' html_theme = 'openstackdocs' # Output file base name for HTML help builder. -htmlhelp_basename = '%sdoc' % project +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 = '%b %d, %Y' -html_last_updated_fmt = '%Y-%m-%d %H:%M' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, -# documentclass [howto/manual]). -latex_documents = [ - ('index', - '%s.tex' % project, - u'%s Documentation' % project, - u'OpenStack Foundation', 'manual'), -] - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} - - -# -- Options for openstackdocstheme ------------------------------------------- -repository_name = 'openstack/python-tackerclient' -bug_project = 'python-tackerclient' -bug_tag = '' +autoprogram_cliff_application = 'openstack' diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..29920d0e --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,31 @@ +.. + 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.) + +================= +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. + +#TODO diff --git a/doc/source/index.rst b/doc/source/index.rst index af3cfab9..601157da 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,25 +1,57 @@ -Python bindings to the OpenStack Tacker API -============================================ +.. + 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 -In order to use the python tacker client directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API. + 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.) + +================================== +python-tackerclient documentation +================================== + +This is a client for OpenStack NFV MANO API. It provides +:doc:`Python API bindings ` (the tackerclient module) and +:doc:`command-line interface (CLI) `. -Command-line Tool -================= -In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-tenant-name``, and ``--os-auth-url``) or set them in environment variables:: +User Documentation +------------------ - export OS_USERNAME=user - export OS_PASSWORD=pass - export OS_TENANT_NAME=tenant - export OS_AUTH_URL=http://auth.example.com:5000/v2.0 +.. toctree:: + :maxdepth: 2 -The command line tool will attempt to reauthenticate using your provided credentials for every request. You can override this behavior by manually supplying an auth token using ``--os-url`` and ``--os-auth-token``. You can alternatively set these environment variables:: + cli/index + reference/index - export OS_URL=http://tacker.example.org:9890/ - export OS_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 +Contributor Guide +----------------- -If tacker server does not require authentication, besides these two arguments or environment variables (We can use any value as token.), we need manually supply ``--os-auth-strategy`` or set the environment variable:: +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. - export OS_AUTH_STRATEGY=noauth +.. toctree:: + :maxdepth: 2 -Once you've configured your authentication parameters, you can run ``tacker -h`` to see a complete listing of available commands. + contributor/index + + +History +------- + +Release notes is available at +http://docs.openstack.org/releasenotes/python-tackerclient/. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..ec900f93 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,38 @@ +.. + 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.) + +================= +Install Guide +================= + +To install ``python-tackerclient``, it is required to have ``pip`` +(in most cases). Make sure that ``pip`` is installed. Then type:: + + $ 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 + +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 new file mode 100644 index 00000000..4ef3cbfc --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,29 @@ +.. + 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.) + +tackerclient Python API +======================== + +Basic Usage +----------- + +#TODO diff --git a/tox.ini b/tox.ini index 114bdeb9..9722f0b0 100644 --- a/tox.ini +++ b/tox.ini @@ -23,6 +23,9 @@ distribute = false [testenv:venv] commands = {posargs} +[testenv:docs] +commands = sphinx-build -W -b html doc/source doc/build/html + [testenv:releasenotes] commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html