diff options
| -rw-r--r-- | .gitignore | 6 | ||||
| -rw-r--r-- | README.rst | 102 | ||||
| -rw-r--r-- | doc/.gitignore | 2 | ||||
| -rw-r--r-- | doc/source/cli/index.rst | 8 | ||||
| -rw-r--r-- | doc/source/cli/nova.rst (renamed from doc/source/man/nova.rst) | 6 | ||||
| -rw-r--r-- | doc/source/conf.py | 62 | ||||
| -rw-r--r-- | doc/source/contributor/index.rst | 16 | ||||
| -rw-r--r-- | doc/source/contributor/testing.rst | 28 | ||||
| -rw-r--r-- | doc/source/index.rst | 96 | ||||
| -rw-r--r-- | doc/source/reference/api/index.rst (renamed from doc/source/api.rst) | 11 | ||||
| -rw-r--r-- | doc/source/reference/deprecation-policy.rst | 32 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 8 | ||||
| -rw-r--r-- | doc/source/user/index.rst | 8 | ||||
| -rw-r--r-- | doc/source/user/shell.rst (renamed from doc/source/shell.rst) | 39 |
14 files changed, 195 insertions, 229 deletions
@@ -18,5 +18,9 @@ novaclient/versioninfo *egg-info .eggs +# Files created by documentation build +/doc/build/ +/doc/source/reference/api/ + # Files created by releasenotes build -releasenotes/build +/releasenotes/build @@ -7,8 +7,9 @@ Team and repository tags .. Change things from this point on -Python bindings to the OpenStack Nova API -========================================= +============================================ +Python bindings to the OpenStack Compute API +============================================ .. image:: https://img.shields.io/pypi/v/python-novaclient.svg :target: https://pypi.python.org/pypi/python-novaclient/ @@ -18,23 +19,14 @@ Python bindings to the OpenStack Nova API :target: https://pypi.python.org/pypi/python-novaclient/ :alt: Downloads -This is a client for the OpenStack Nova API. There's a Python API (the -``novaclient`` module), and a command-line script (``nova``). Each -implements 100% of the OpenStack Nova API. - -See the `OpenStack CLI guide`_ for information on how to use the ``nova`` -command-line tool. You may also want to look at the -`OpenStack API documentation`_. - -.. _OpenStack CLI Guide: http://docs.openstack.org/cli-reference/nova.html -.. _OpenStack API documentation: http://developer.openstack.org/api-ref-compute-v2.1.html - -python-novaclient is licensed under the Apache License like the rest of -OpenStack. +This is a client for the OpenStack Compute API. It provides a Python API (the +``novaclient`` module) and a command-line script (``nova``). Each implements +100% of the OpenStack Compute API. * License: Apache License, Version 2.0 * `PyPi`_ - package installation * `Online Documentation`_ +* `Launchpad project`_ - release management * `Blueprints`_ - feature specifications * `Bugs`_ - issue tracking * `Source`_ @@ -42,86 +34,10 @@ OpenStack. * `How to Contribute`_ .. _PyPi: https://pypi.python.org/pypi/python-novaclient -.. _Online Documentation: http://docs.openstack.org/developer/python-novaclient +.. _Online Documentation: http://docs.openstack.org/python-novaclient +.. _Launchpad project: https://launchpad.net/python-novaclient .. _Blueprints: https://blueprints.launchpad.net/python-novaclient .. _Bugs: https://bugs.launchpad.net/python-novaclient .. _Source: https://git.openstack.org/cgit/openstack/python-novaclient .. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html .. _Specs: http://specs.openstack.org/openstack/nova-specs/ - - -.. contents:: Contents: - :local: - -Command-line API ----------------- - -Installing this package gets you a shell command, ``nova``, that you -can use to interact with any OpenStack cloud. - -You'll need to provide your OpenStack username and password. You can do this -with the ``--os-username``, ``--os-password`` and ``--os-project-name`` -params, but it's easier to just set them as environment variables:: - - export OS_USERNAME=<username> - export OS_PASSWORD=<password> - export OS_PROJECT_NAME=<project-name> - - -You will also need to define the authentication url with ``--os-auth-url`` -and the version of the API with ``--os-compute-api-version``. Or set them as -environment variables as well and set the OS_AUTH_URL to the keystone endpoint:: - - export OS_AUTH_URL=http://<url-to-openstack-keystone>:5000/v3/ - export OS_COMPUTE_API_VERSION=2.1 - - -Since Keystone can return multiple regions in the Service Catalog, you -can specify the one you want with ``--os-region-name`` (or -``export OS_REGION_NAME``). It defaults to the first in the list returned. - -You'll find complete documentation on the shell by running -``nova help`` - -Python API ----------- - -There's also a complete Python API, with documentation linked below. - - -To use with keystone as the authentication system:: - - >>> from keystoneauth1.identity import v3 - >>> from keystoneauth1 import session - >>> from novaclient import client - >>> auth = v3.Password(auth_url='http://example.com:5000/v3', - ... username='username', - ... password='password', - ... project_name='project-name', - ... user_domain_id='default', - ... project_domain_id='default') - >>> sess = session.Session(auth=auth) - >>> nova = client.Client("2.1", session=sess) - >>> nova.flavors.list() - [...] - >>> nova.servers.list() - [...] - >>> nova.keypairs.list() - [...] - - -Testing -------- - -There are multiple test targets that can be run to validate the code. - -* tox -e pep8 - style guidelines enforcement -* tox -e py27 - traditional unit testing -* tox -e functional - live functional testing against an existing - openstack - -Functional testing assumes the existence of a `clouds.yaml` file as supported -by `os-client-config` (http://docs.openstack.org/developer/os-client-config) -It assumes the existence of a cloud named `devstack` that behaves like a normal -devstack installation with a demo and an admin user/tenant - or clouds named -`functional_admin` and `functional_nonadmin`. diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 8e0be80f..00000000 --- a/doc/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -build/ -source/ref/ diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 00000000..ce291731 --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,8 @@ +=============== + CLI Reference +=============== + +.. toctree:: + :maxdepth: 2 + + nova diff --git a/doc/source/man/nova.rst b/doc/source/cli/nova.rst index 56e56b59..c3c6caf4 100644 --- a/doc/source/man/nova.rst +++ b/doc/source/cli/nova.rst @@ -1,6 +1,6 @@ -==== -nova -==== +====== + nova +====== SYNOPSIS diff --git a/doc/source/conf.py b/doc/source/conf.py index 4813effb..19d10bde 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,37 +22,46 @@ sys.path.insert(0, ROOT) sys.path.insert(0, BASE_DIR) +# TODO(stephenfin): This looks like something that pbr's autodoc integration +# could be doing for us. Investigate. + def gen_ref(ver, title, names): - refdir = os.path.join(BASE_DIR, "ref") + refdir = os.path.join(BASE_DIR, "reference", "api") pkg = "novaclient" if ver: pkg = "%s.%s" % (pkg, ver) refdir = os.path.join(refdir, ver) if not os.path.exists(refdir): os.makedirs(refdir) - idxpath = os.path.join(refdir, "index.rst") - with open(idxpath, "w") as idx: - idx.write(("%(title)s\n" - "%(signs)s\n" - "\n" - ".. toctree::\n" - " :maxdepth: 1\n" - "\n") % {"title": title, "signs": "=" * len(title)}) - for name in names: - idx.write(" %s\n" % name) - rstpath = os.path.join(refdir, "%s.rst" % name) - with open(rstpath, "w") as rst: - rst.write(("%(title)s\n" - "%(signs)s\n" - "\n" - ".. automodule:: %(pkg)s.%(name)s\n" - " :members:\n" - " :undoc-members:\n" - " :show-inheritance:\n" - " :noindex:\n") - % {"title": name.capitalize(), - "signs": "=" * len(name), - "pkg": pkg, "name": name}) + + # we don't want to write index files for top-level directories - only + # sub-directories + if ver: + idxpath = os.path.join(refdir, "index.rst") + with open(idxpath, "w") as idx: + idx.write(("%(title)s\n" + "%(signs)s\n" + "\n" + ".. toctree::\n" + " :maxdepth: 1\n" + "\n") % {"title": title, "signs": "=" * len(title)}) + for name in names: + idx.write(" %s\n" % name) + + for name in names: + rstpath = os.path.join(refdir, "%s.rst" % name) + with open(rstpath, "w") as rst: + rst.write(("%(title)s\n" + "%(signs)s\n" + "\n" + ".. automodule:: %(pkg)s.%(name)s\n" + " :members:\n" + " :undoc-members:\n" + " :show-inheritance:\n" + " :noindex:\n") + % {"title": name.capitalize(), + "signs": "=" * len(name), + "pkg": pkg, "name": name}) def get_module_names(): @@ -107,14 +116,11 @@ pygments_style = 'sphinx' # Sphinx are currently 'default' and 'sphinxdoc'. html_theme = 'default' -# Output file base name for HTML help builder. -htmlhelp_basename = 'python-novaclientdoc' - # -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('man/nova', 'nova', 'OpenStack Nova command line client', + ('cli/nova', 'nova', 'OpenStack Nova command line client', ['OpenStack Contributors'], 1), ] diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..cf8dccae --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,16 @@ +=================== + Contributor Guide +=================== + +Code is hosted at `git.openstack.org`__. Submit bugs to the Nova project on +`Launchpad`__. Submit code to the `openstack/python-novaclient` project using +`Gerrit`__. + +__ https://git.openstack.org/cgit/openstack/python-novaclient +__ https://launchpad.net/nova +__ http://docs.openstack.org/infra/manual/developers.html#development-workflow + +.. toctree:: + :maxdepth: 2 + + testing diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst new file mode 100644 index 00000000..c4e59143 --- /dev/null +++ b/doc/source/contributor/testing.rst @@ -0,0 +1,28 @@ +========= + Testing +========= + +The preferred way to run the unit tests is using ``tox``. There are multiple +test targets that can be run to validate the code. + +``tox -e pep8`` + + Style guidelines enforcement. + +``tox -e py27`` + + Traditional unit testing. + +``tox -e functional`` + + Live functional testing against an existing OpenStack instance. + +Functional testing assumes the existence of a `clouds.yaml` file as supported +by `os-client-config <http://docs.openstack.org/developer/os-client-config>`__ +It assumes the existence of a cloud named `devstack` that behaves like a normal +DevStack installation with a demo and an admin user/tenant - or clouds named +`functional_admin` and `functional_nonadmin`. + +Refer to `Consistent Testing Interface`__ for more details. + +__ http://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 4421c910..4ee0122c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,13 +1,14 @@ -Python bindings to the OpenStack Nova API -========================================= +=========================================== + Python bindings to the OpenStack Nova API +=========================================== This is a client for OpenStack Nova API. There's :doc:`a Python API -<api>` (the :mod:`novaclient` module), and a :doc:`command-line script -<shell>` (installed as :program:`nova`). Each implements the entire -OpenStack Nova API. +<reference/api/index>` (the :mod:`novaclient` module), and a :doc:`command-line +script </user/shell>` (installed as :program:`nova`). Each implements the +entire OpenStack Nova API. -You'll need credentials for an OpenStack cloud that implements the -Compute API, such as TryStack, HP, or Rackspace, in order to use the nova client. +You'll need credentials for an OpenStack cloud that implements the Compute API, +such as TryStack, HP, or Rackspace, in order to use the nova client. .. seealso:: @@ -17,83 +18,10 @@ Compute API, such as TryStack, HP, or Rackspace, in order to use the nova client __ https://developer.openstack.org/api-guide/compute/index.html -Contents: - .. toctree:: :maxdepth: 2 - shell - api - ref/index - ref/v2/index - -Contributing -============ - -Code is hosted at `git.openstack.org`_. Submit bugs to the Nova project on -`Launchpad`_. Submit code to the openstack/python-novaclient project using -`Gerrit`_. - -.. _git.openstack.org: https://git.openstack.org/cgit/openstack/python-novaclient -.. _Launchpad: https://launchpad.net/nova -.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow - -Testing -------- - -The preferred way to run the unit tests is using ``tox``. - -See `Consistent Testing Interface`_ for more details. - -.. _Consistent Testing Interface: http://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst - -Deprecating commands -==================== - -There are times when commands need to be deprecated due to rename or removal. -The process for command deprecation is: - - 1. Push up a change for review which deprecates the command(s). - - - The change should print a deprecation warning to stderr each time a - deprecated command is used. - - That warning message should include a rough timeline for when the command - will be removed and what should be used instead, if anything. - - The description in the help text for the deprecated command should mark - that it is deprecated. - - The change should include a release note with the ``deprecations`` section - filled out. - - The deprecation cycle is typically the first client release *after* the - next *full* Nova server release so that there is at least six months of - deprecation. - - 2. Once the change is approved, have a member of the `nova-release`_ team - release a new version of python-novaclient. - - .. _nova-release: https://review.openstack.org/#/admin/groups/147,members - - 3. Example: `<https://review.openstack.org/#/c/185141/>`_ - - This change was made while the Nova 12.0.0 Liberty release was in - development. The current version of python-novaclient at the time was - 2.25.0. Once the change was merged, python-novaclient 2.26.0 was released. - Since there was less than six months before 12.0.0 would be released, the - deprecation cycle ran through the 13.0.0 Nova server release. - - -Man Page -======== - -.. toctree:: - :maxdepth: 1 - - man/nova - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + user/index + reference/index + cli/index + contributor/index diff --git a/doc/source/api.rst b/doc/source/reference/api/index.rst index 450d66d9..c5ed6d88 100644 --- a/doc/source/api.rst +++ b/doc/source/reference/api/index.rst @@ -1,5 +1,6 @@ -The :mod:`novaclient` Python API -================================ +================================== + The :mod:`novaclient` Python API +================================== .. module:: novaclient :synopsis: A client for the OpenStack Nova API. @@ -18,7 +19,6 @@ Here ``VERSION`` can be a string or ``novaclient.api_versions.APIVersion`` obj. If you prefer string value, you can use ``1.1`` (deprecated now), ``2`` or ``2.X`` (where X is a microversion). - Alternatively, you can create a client instance using the keystoneauth session API:: @@ -98,7 +98,6 @@ Then call methods on its managers:: .. _1493576: https://launchpad.net/bugs/1493576 - Reference --------- @@ -107,5 +106,5 @@ For more information, see the reference: .. toctree:: :maxdepth: 2 - ref/index - ref/v2/index + v2/index + exceptions diff --git a/doc/source/reference/deprecation-policy.rst b/doc/source/reference/deprecation-policy.rst new file mode 100644 index 00000000..0085bca9 --- /dev/null +++ b/doc/source/reference/deprecation-policy.rst @@ -0,0 +1,32 @@ +Deprecating commands +==================== + +There are times when commands need to be deprecated due to rename or removal. +The process for command deprecation is: + +1. Push up a change for review which deprecates the command(s). + + - The change should print a deprecation warning to ``stderr`` each time a + deprecated command is used. + - That warning message should include a rough timeline for when the command + will be removed and what should be used instead, if anything. + - The description in the help text for the deprecated command should mark + that it is deprecated. + - The change should include a release note with the ``deprecations`` section + filled out. + - The deprecation cycle is typically the first client release *after* the + next *full* nova server release so that there is at least six months of + deprecation. + +2. Once the change is approved, have a member of the `nova-release`_ team + release a new version of `python-novaclient`. + + .. _nova-release: https://review.openstack.org/#/admin/groups/147,members + +3. Example: `<https://review.openstack.org/#/c/185141/>`_ + + This change was made while the nova 12.0.0 Liberty release was in + development. The current version of `python-novaclient` at the time was + 2.25.0. Once the change was merged, `python-novaclient` 2.26.0 was released. + Since there was less than six months before 12.0.0 would be released, the + deprecation cycle ran through the 13.0.0 nova server release. diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 00000000..92e93855 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,8 @@ +Reference +========= + +.. toctree:: + :maxdepth: 1 + + api/index + deprecation-policy diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..3c54920b --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,8 @@ +============ + User Guide +============ + +.. toctree:: + :maxdepth: 2 + + shell diff --git a/doc/source/shell.rst b/doc/source/user/shell.rst index 6f72c3a3..b2d7d9ef 100644 --- a/doc/source/shell.rst +++ b/doc/source/user/shell.rst @@ -1,19 +1,20 @@ -The :program:`nova` shell utility -================================= +=================================== + The :program:`nova` Shell Utility +=================================== .. program:: nova .. highlight:: bash -The :program:`nova` shell utility interacts with OpenStack Nova API -from the command line. It supports the entirety of the OpenStack Nova API. +The :program:`nova` shell utility interacts with OpenStack Nova API from the +command line. It supports the entirety of the OpenStack Nova API. -First, you'll need an OpenStack Nova account and an API key. You get this -by using the `nova-manage` command in OpenStack Nova. +First, you'll need an OpenStack Nova account and an API key. You get this by +using the `nova-manage` command in OpenStack Nova. You'll need to provide :program:`nova` with your OpenStack username and API key. You can do this with the `--os-username`, `--os-password` and `--os-tenant-id` options, but it's easier to just set them as environment -variables by setting two environment variables: +variables by setting some environment variables: .. envvar:: OS_USERNAME @@ -35,18 +36,32 @@ variables by setting two environment variables: The OpenStack API version. +.. envvar:: OS_REGION_NAME + + The Keystone region name. Defaults to the first region if multiple regions + are available. + For example, in Bash you'd use:: export OS_USERNAME=yourname export OS_PASSWORD=yadayadayada export OS_TENANT_NAME=myproject - export OS_AUTH_URL=http://... - export OS_COMPUTE_API_VERSION=2 + export OS_AUTH_URL=http://<url-to-openstack-keystone>:5000/v3/ + export OS_COMPUTE_API_VERSION=2.1 From there, all shell commands take the form:: nova <command> [arguments...] -Run :program:`nova help` to get a full list of all possible commands, -and run :program:`nova help <command>` to get detailed help for that -command. +Run :program:`nova help` to get a full list of all possible commands, and run +:program:`nova help <command>` to get detailed help for that command. + +Reference +--------- + +For more information, see the reference: + +.. toctree:: + :maxdepth: 2 + + /cli/nova |