openstack/python-novaclient
Code Issues Proposed changes

doc: Create directory structure for docs migration

Browse Source 
The spec [1] recommends the following sections:

- install
- contributor
- configuration
- cli
- admin
- user
- reference

Only a few of these are useful here:

- contributor
- cli
- user
- reference

Add these and populate them.

[1] specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration

Change-Id: I8a9ddcc915f25ebfaa1e994dba6c15883bd2715d
This commit is contained in:
Stephen Finucane 2017-07-04 11:06:56 +01:00
parent bd0a2adefe
commit e11efd8d76
14 changed files with 195 additions and 229 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.gitignore vendored
View File

@ -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

102
README.rst
View File

@ -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`.

2
doc/.gitignore vendored
View File

@ -1,2 +0,0 @@
build/
source/ref/

8
doc/source/cli/index.rst Normal file
View File

@ -0,0 +1,8 @@
===============
CLI Reference
===============
.. toctree::
:maxdepth: 2
nova

6
doc/source/man/nova.rst → doc/source/cli/nova.rst
View File

@ -1,6 +1,6 @@
====
nova
====
======
nova
======
SYNOPSIS

62
doc/source/conf.py
View File

@ -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),
]

16
doc/source/contributor/index.rst Normal file
View File

@ -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

28
doc/source/contributor/testing.rst Normal file
View File

@ -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

96
doc/source/index.rst
View File

@ -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

11
doc/source/api.rst → doc/source/reference/api/index.rst
View File

@ -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

32
doc/source/reference/deprecation-policy.rst Normal file
View File

@ -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.

8
doc/source/reference/index.rst Normal file
View File

@ -0,0 +1,8 @@
Reference
=========
.. toctree::
:maxdepth: 1
api/index
deprecation-policy

8
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,8 @@
============
User Guide
============
.. toctree::
:maxdepth: 2
shell

39
doc/source/shell.rst → doc/source/user/shell.rst
View File

@ -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