python-openstackclient/doc/source/index.rst

===============
OpenStackClient
===============

OpenStackClient (aka OSC) is a command-line client for OpenStack that
brings the command set for Compute, Identity, Image, Object Storage and
Block Storage APIs together in a single shell with a uniform command
structure.

User Documentation
------------------

.. toctree::
   :maxdepth: 1

   Manual Page <man/openstack>
   command-list
   commands
   configuration
   plugins
   plugin-commands
   authentication
   interactive
   humaninterfaceguide
   backwards-incompatible

Getting Started
---------------

* Try :doc:`some commands <command-list>`
* Read the source `on OpenStack's Git server`_
* Install OpenStackClient from `PyPi`_ or a `tarball`_

Release Notes
-------------

.. toctree::
   :maxdepth: 1

   Release Notes <http://docs.openstack.org/releasenotes/python-openstackclient>
   history

Developer Documentation
-----------------------

.. toctree::
   :maxdepth: 1

   developing
   command-beta
   command-options
   command-wrappers
   command-errors
   command-logs
   specs/commands

Project Goals
-------------

* Use the OpenStack Python API libraries, extending or replacing them as required
* Use a consistent naming and structure for commands and arguments
* Provide consistent output formats with optional machine parseable formats
* Use a single-binary approach that also contains an embedded shell that can execute
  multiple commands on a single authentication (see libvirt's virsh for an example)
* Independence from the OpenStack project names; only API names are referenced (to
  the extent possible)

Contributing
============

OpenStackClient utilizes all of the usual OpenStack processes and requirements for
contributions.  The code is hosted `on OpenStack's Git server`_. `Bug reports`_
and `blueprints`_ may be submitted to the :code:`python-openstackclient` project
on `Launchpad`_.  Code may be submitted to the
:code:`openstack/python-openstackclient` project using `Gerrit`_.
Developers may also be found in the `IRC channel`_ ``#openstack-sdks``.

.. _`on OpenStack's Git server`: https://git.openstack.org/cgit/openstack/python-openstackclient/tree
.. _Launchpad: https://launchpad.net/python-openstackclient
.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow
.. _Bug reports: https://bugs.launchpad.net/python-openstackclient/+bugs
.. _blueprints: https://blueprints.launchpad.net/python-openstackclient
.. _PyPi: https://pypi.python.org/pypi/python-openstackclient
.. _tarball: http://tarballs.openstack.org/python-openstackclient
.. _IRC channel: https://wiki.openstack.org/wiki/IRC

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Update docs and release notes for 0.4.0 Change-Id: Iad6cfe5dee63adb9e60a0ea9811217b3175eb99c 2014-05-15 09:05:37 -05:00			`===============`
			`OpenStackClient`
			`===============`
First commit 2012-04-18 13:16:39 -05:00
Update docs and release notes for 0.4.0 Change-Id: Iad6cfe5dee63adb9e60a0ea9811217b3175eb99c 2014-05-15 09:05:37 -05:00			`OpenStackClient (aka OSC) is a command-line client for OpenStack that`
Use Block Storage instead of Volume Volume is better to be replaced by Block Storage in the doc. Change-Id: I736669ee01c7385b6e701cb20f4334eff1c49286 2015-11-08 22:05:15 +08:00			`brings the command set for Compute, Identity, Image, Object Storage and`
			`Block Storage APIs together in a single shell with a uniform command`
			`structure.`
First commit 2012-04-18 13:16:39 -05:00
Add developer documentation OSC was missing developer docs, these are critically helpful for new developers. Add sections related to running tests (tox, functional and with the debugger), and generating docs locally. implements bp: developer-documentation Change-Id: I428d89c3e5fc335864bc4f7843506043ec332fe5 2015-08-08 01:07:07 -07:00			`User Documentation`
			`------------------`
First commit 2012-04-18 13:16:39 -05:00
			`.. toctree::`
			`:maxdepth: 1`

Clean up for next release * Release notes * Docs Table of Contents Change-Id: I4bef26ed348923671a2b50f90606661d519b40e3 2016-04-18 13:49:01 -05:00			`Manual Page <man/openstack>`
Begin copying wiki command list here * Sort by command objects * Drop the comparison to the project CLIs * Minor updates to command help to match docs Initially include the cross-API commands to establish the structure and format. Change-Id: I77a7b3c89e088b66aa62941e29ce0b65b532285b 2014-11-17 16:42:30 -06:00			`command-list`
Prep for 0.2 release (0.2.rc1) * rename HACKING to HACKING.rst and refer to the common OpenStack HACKING file * add the barest of pointers to the wiki, etc. to the source docs * add a bare-bones man page Change-Id: I80e5b972af645f14ef17ae87f182ab09cb08dabe 2013-07-29 17:05:02 -05:00			`commands`
Begin documenting --os-cloud Change-Id: Id2e98ac5601840f6d380cabcd578f1a6d6d9b245 2015-03-03 23:12:07 -06:00			`configuration`
Update docs for plugins and release notes * Fill out the existing command and man page * Add a plugins page. * Begin the release notes for 0.3.0 Change-Id: I4527fed28a10a9d79fc8f6c1d925a4bf0d0a7a36 2013-12-05 13:23:44 -06:00			`plugins`
autodocument commands from plugins using stevedore.sphinxext conflicting command names are a painpoint, so is manually updating a list. let's autodocument the commands that are being use by existing osc supporters. Change-Id: If37d81dfd57cc79803668b64be1ccd776e319572 2015-10-16 02:08:05 -04:00			`plugin-commands`
Add authentication description doc This is represents the current operation Closes-Bug: #1337422 Change-Id: I8092e7723b563647e13b6e2f0b7901a16572b6c7 2014-10-24 10:34:41 -05:00			`authentication`
Add documentation of interactive mode This is a light description with some examples. Change-Id: Iff9ad904a150f2bb7673bd4106cf26bcefec08b9 2014-12-02 16:57:22 -06:00			`interactive`
Copy HIG from wiki This is a basic port of the Human Interface Guide from the OpenStack wiki to our docs. Content changes for updating, etc, will follow in a separate review. Change-Id: Id031cd6a27e045b249e16d00e41be24c55fb3c29 2015-01-13 17:03:01 -06:00			`humaninterfaceguide`
Add a doc that dictates backwards incompatible changes start tracking any changes in a standard format, so users may have a heads up about any impacts. Change-Id: Ibc06926a53592e927d11440362cd3598e0d4b2bf Closes-Bug: 1406470 2015-04-23 21:25:56 -04:00			`backwards-incompatible`
Prep for 0.2 release (0.2.rc1) * rename HACKING to HACKING.rst and refer to the common OpenStack HACKING file * add the barest of pointers to the wiki, etc. to the source docs * add a bare-bones man page Change-Id: I80e5b972af645f14ef17ae87f182ab09cb08dabe 2013-07-29 17:05:02 -05:00
First commit 2012-04-18 13:16:39 -05:00			`Getting Started`
			`---------------`

Copy wiki content to index page Copy the content from the main wiki page that is not covered elsewhere in these docs to the index page. Change-Id: I94b68b7a0117d08fc8aba961c6de728118ef794e 2015-01-13 17:23:33 -06:00			* Try :doc:`some commands <command-list>`
Acknowlege git.o.o as OpenStack's git server OpenStack's cannonical git server is at git.o.o this patch updates the index.rst to reflect that. Change-Id: I54eeea7fab2e0f64ca9f23f7c328e2ff19721a41 2014-09-18 17:05:07 -04:00			* Read the source `on OpenStack's Git server`_
Copy wiki content to index page Copy the content from the main wiki page that is not covered elsewhere in these docs to the index page. Change-Id: I94b68b7a0117d08fc8aba961c6de728118ef794e 2015-01-13 17:23:33 -06:00			* Install OpenStackClient from `PyPi`_ or a `tarball`_
Prep for 0.2 release (0.2.rc1) * rename HACKING to HACKING.rst and refer to the common OpenStack HACKING file * add the barest of pointers to the wiki, etc. to the source docs * add a bare-bones man page Change-Id: I80e5b972af645f14ef17ae87f182ab09cb08dabe 2013-07-29 17:05:02 -05:00
Add a changelog to see all changes into tagged releases in addition to release notes, it'll be nice to also see the changelog that happened between releases. Change-Id: I4548be22c377ec12f0398a248391384126506715 2015-11-30 16:30:42 -05:00			`Release Notes`
			`-------------`

			`.. toctree::`
			`:maxdepth: 1`

include old release notes in reno Currently OSC release notes are in the OpenStack releasenote site. There is a collection of old non-reno release notes in our docs folder. Move the non-reno release notes to the reno directionary. Change-Id: Ie51fd1e1115d606e5d2739014d3720eedc8dc225 2016-05-28 10:58:23 +08:00			`Release Notes <http://docs.openstack.org/releasenotes/python-openstackclient>`
Add a changelog to see all changes into tagged releases in addition to release notes, it'll be nice to also see the changelog that happened between releases. Change-Id: I4548be22c377ec12f0398a248391384126506715 2015-11-30 16:30:42 -05:00			`history`

Add developer documentation OSC was missing developer docs, these are critically helpful for new developers. Add sections related to running tests (tox, functional and with the debugger), and generating docs locally. implements bp: developer-documentation Change-Id: I428d89c3e5fc335864bc4f7843506043ec332fe5 2015-08-08 01:07:07 -07:00			`Developer Documentation`
			`-----------------------`

			`.. toctree::`
			`:maxdepth: 1`

			`developing`
Devref: Command Beta The devref proposes OSC support for beta commands. Change-Id: I538a38be33734faf6eb69a3cb50946b2396b0c57 2016-04-12 16:07:30 -05:00			`command-beta`
Add Command Options guideline doc Add a developer guideline for command options to define the options used across multiple commands and make them behave consistently. Change-Id: I1dbbafe8061e10b271cd55cac056731508c52204 2015-10-20 15:44:38 -05:00			`command-options`
Add command wrapper doc This is a follow-up to I6c750730963615895f5d9953487d2d5a905885a8 that removed a command deprecation warning wrapper. This documents the technique for later use. Change-Id: Ieaa1e6b7eed4e5b037b4bfb6cf488e1290fc69f7 2015-11-20 10:36:40 -06:00			`command-wrappers`
Add doc describing how to handle API errors Include the following scenarios: * general external errors * a command with multiple API calls Change-Id: Ie5c4b775e11898bacf2156a34457f5397fd2c891 2016-03-09 11:47:28 -06:00			`command-errors`
Add doc for logger usage This patch adds a doc to record rules of usage of loggers in OSC. Change-Id: I27a09f9abb523393031560e2310bfdd1af0b8922 Implements: blueprint log-usage 2016-06-15 14:09:08 +08:00			`command-logs`
Doc: Add optional command specs process The developer documentation has been updated to include an optional command specs process. This process may be used to work out the specifications for new commands, objects and actions before their implementation. This new process could assist in the implementation of additional neutron support in OSC. Change-Id: I62f7472435a9caacee0d1b4c8d35417c123b5a44 2015-12-10 13:30:21 -06:00			`specs/commands`
Copy wiki content to index page Copy the content from the main wiki page that is not covered elsewhere in these docs to the index page. Change-Id: I94b68b7a0117d08fc8aba961c6de728118ef794e 2015-01-13 17:23:33 -06:00
			`Project Goals`
			`-------------`

			`* Use the OpenStack Python API libraries, extending or replacing them as required`
			`* Use a consistent naming and structure for commands and arguments`
			`* Provide consistent output formats with optional machine parseable formats`
			`* Use a single-binary approach that also contains an embedded shell that can execute`
			`multiple commands on a single authentication (see libvirt's virsh for an example)`
			`* Independence from the OpenStack project names; only API names are referenced (to`
			`the extent possible)`
First commit 2012-04-18 13:16:39 -05:00
			`Contributing`
			`============`

Copy wiki content to index page Copy the content from the main wiki page that is not covered elsewhere in these docs to the index page. Change-Id: I94b68b7a0117d08fc8aba961c6de728118ef794e 2015-01-13 17:23:33 -06:00			`OpenStackClient utilizes all of the usual OpenStack processes and requirements for`
			contributions. The code is hosted `on OpenStack's Git server`_. `Bug reports`_
			and `blueprints`_ may be submitted to the :code:`python-openstackclient` project
			on `Launchpad`_. Code may be submitted to the
			:code:`openstack/python-openstackclient` project using `Gerrit`_.
Add a reference to the IRC channels As the name of the associated IRC channel for this project is not completely obvious, add a reference to the doc index page so that it may be found easier. Change-Id: I6cb6e2571bff73db6d983cd96fe6d03319d6577c 2015-06-03 02:34:07 +02:00			Developers may also be found in the `IRC channel`_ ``#openstack-sdks``.
First commit 2012-04-18 13:16:39 -05:00
Copy wiki content to index page Copy the content from the main wiki page that is not covered elsewhere in these docs to the index page. Change-Id: I94b68b7a0117d08fc8aba961c6de728118ef794e 2015-01-13 17:23:33 -06:00			.. _`on OpenStack's Git server`: https://git.openstack.org/cgit/openstack/python-openstackclient/tree
Update Contributing blurb in the docs. Contributing blurb previously mentioned social coding and Github. The OpenStack contribution workflow is slightly different. Provide details on Github, LP, and Gerrit. Change-Id: Ie5ecd25e5828de611561f37b3acbccc5cf3f0d04 2012-06-22 10:24:44 -07:00			`.. _Launchpad: https://launchpad.net/python-openstackclient`
Workflow documentation is now in infra-manual Replace URLs for workflow documentation to appropriate parts of the OpenStack Project Infrastructure Manual. Change-Id: Id09c9bdf8804c1ed90e49606e76ffbff1d96a7c2 2014-12-05 03:30:40 +00:00			`.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow`
Copy wiki content to index page Copy the content from the main wiki page that is not covered elsewhere in these docs to the index page. Change-Id: I94b68b7a0117d08fc8aba961c6de728118ef794e 2015-01-13 17:23:33 -06:00			`.. _Bug reports: https://bugs.launchpad.net/python-openstackclient/+bugs`
			`.. _blueprints: https://blueprints.launchpad.net/python-openstackclient`
			`.. _PyPi: https://pypi.python.org/pypi/python-openstackclient`
			`.. _tarball: http://tarballs.openstack.org/python-openstackclient`
Add a reference to the IRC channels As the name of the associated IRC channel for this project is not completely obvious, add a reference to the doc index page so that it may be found easier. Change-Id: I6cb6e2571bff73db6d983cd96fe6d03319d6577c 2015-06-03 02:34:07 +02:00			`.. _IRC channel: https://wiki.openstack.org/wiki/IRC`
First commit 2012-04-18 13:16:39 -05:00
Enhance the theming for modules page Also fixes a few small docstring syntax errors Change-Id: I85eb968e32c1191cf5d60d02deff2ab7f3291074 2014-11-18 00:16:21 -05:00			`Indices and Tables`
			`==================`
First commit 2012-04-18 13:16:39 -05:00
			* :ref:`genindex`
			* :ref:`modindex`
			* :ref:`search`