From 6c0e4d7a3940ba6d4d11d0c89933cc00b898ed9e Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Fri, 11 Oct 2019 03:48:51 +0900 Subject: PDF documentation build Also reorganizes the document structure to match both HTML and PDF docs. Story: 2006100 Task: 35143 Change-Id: Ie3f38e2ecf52e6a6cbd52bb36196e6f589f1ca0f --- doc/source/conf.py | 14 ++++ doc/source/contributor/deprecation-policy.rst | 32 ++++++++ doc/source/contributor/index.rst | 1 + doc/source/index.rst | 4 +- doc/source/reference/api/index.rst | 109 -------------------------- doc/source/reference/deprecation-policy.rst | 32 -------- doc/source/reference/index.rst | 6 +- doc/source/user/index.rst | 1 + doc/source/user/python-api.rst | 104 ++++++++++++++++++++++++ doc/source/user/shell.rst | 10 +-- 10 files changed, 158 insertions(+), 155 deletions(-) create mode 100644 doc/source/contributor/deprecation-policy.rst delete mode 100644 doc/source/reference/api/index.rst delete mode 100644 doc/source/reference/deprecation-policy.rst create mode 100644 doc/source/user/python-api.rst (limited to 'doc') diff --git a/doc/source/conf.py b/doc/source/conf.py index f90c50ad..5e69e49c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -72,6 +72,20 @@ html_theme = 'openstackdocs' # robots.txt. html_extra_path = ['_extra'] +# -- Options for LaTeX output ------------------------------------------------- + +latex_documents = [ + ('index', 'doc-python-novaclient.tex', u'python-novaclient Documentation', + u'OpenStack Foundation', 'manual'), +] + +latex_elements = { + 'extraclassoptions': 'openany,oneside', + 'preamble': r'\setcounter{tocdepth}{4}', + 'makeindex': '', + 'printindex': '', +} + # -- Options for openstackdocstheme ------------------------------------------- repository_name = 'openstack/python-novaclient' diff --git a/doc/source/contributor/deprecation-policy.rst b/doc/source/contributor/deprecation-policy.rst new file mode 100644 index 00000000..c7e84fbb --- /dev/null +++ b/doc/source/contributor/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.opendev.org/#/admin/groups/147,members + +3. Example: ``_ + + 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/contributor/index.rst b/doc/source/contributor/index.rst index 58b9bd7e..50fd507f 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -15,3 +15,4 @@ __ https://docs.openstack.org/infra/manual/developers.html#development-workflow microversions testing + deprecation-policy diff --git a/doc/source/index.rst b/doc/source/index.rst index 243c9497..5c088795 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,7 +3,7 @@ =========================================== This is a client for OpenStack Nova API. There's a :doc:`Python API -` (the :mod:`novaclient` module), and a :doc:`command-line +` (the :mod:`novaclient` module), and a :doc:`command-line script ` (installed as :program:`nova`). Each implements the entire OpenStack Nova API. @@ -22,6 +22,6 @@ such as TryStack, HP, or Rackspace, in order to use the nova client. :maxdepth: 2 user/index - reference/index cli/index + reference/index contributor/index diff --git a/doc/source/reference/api/index.rst b/doc/source/reference/api/index.rst deleted file mode 100644 index d4959400..00000000 --- a/doc/source/reference/api/index.rst +++ /dev/null @@ -1,109 +0,0 @@ -================================== - The :mod:`novaclient` Python API -================================== - -.. module:: novaclient - :synopsis: A client for the OpenStack Nova API. - :noindex: - -.. currentmodule:: novaclient - -Usage ------ - -First create a client instance with your credentials:: - - >>> from novaclient import client - >>> nova = client.Client(VERSION, USERNAME, PASSWORD, PROJECT_ID, AUTH_URL) - -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:: - - >>> from keystoneauth1 import loading - >>> from keystoneauth1 import session - >>> from novaclient import client - >>> loader = loading.get_plugin_loader('password') - >>> auth = loader.load_from_options(auth_url=AUTH_URL, - ... username=USERNAME, - ... password=PASSWORD, - ... project_id=PROJECT_ID) - >>> sess = session.Session(auth=auth) - >>> nova = client.Client(VERSION, session=sess) - -If you have PROJECT_NAME instead of a PROJECT_ID, use the project_name -parameter. Similarly, if your cloud uses keystone v3 and you have a DOMAIN_NAME -or DOMAIN_ID, provide it as `user_domain_(name|id)` and if you are using a -PROJECT_NAME also provide the domain information as `project_domain_(name|id)`. - -novaclient adds 'python-novaclient' and its version to the user-agent string -that keystoneauth produces. If you are creating an application using novaclient -and want to register a name and version in the user-agent string, pass those -to the Session:: - - >>> sess = session.Session( - ... auth=auth, app_name'nodepool', app_version'1.2.3') - -If you are making a library that consumes novaclient but is not an end-user -application, you can append a (name, version) tuple to the session's -`additional_user_agent` property:: - - >>> sess = session.Session(auth=auth) - >>> sess.additional_user_agent.append(('shade', '1.2.3')) - -For more information on this keystoneauth API, see -:keystoneauth-doc:`Using Sessions `. - -It is also possible to use an instance as a context manager in which case -there will be a session kept alive for the duration of the with statement:: - - >>> from novaclient import client - >>> with client.Client(VERSION, USERNAME, PASSWORD, - ... PROJECT_ID, AUTH_URL) as nova: - ... nova.servers.list() - ... nova.flavors.list() - ... - -It is also possible to have a permanent (process-long) connection pool, -by passing a connection_pool=True:: - - >>> from novaclient import client - >>> nova = client.Client(VERSION, USERNAME, PASSWORD, PROJECT_ID, - ... AUTH_URL, connection_pool=True) - -Then call methods on its managers:: - - >>> nova.servers.list() - [] - - >>> nova.flavors.list() - [, - , - , - , - , - , - ] - - >>> fl = nova.flavors.find(ram=512) - >>> nova.servers.create("my-server", flavor=fl) - - -.. warning:: Direct initialization of ``novaclient.v2.client.Client`` object - can cause you to "shoot yourself in the foot". See launchpad bug-report - `1493576`_ for more details. - -.. _1493576: https://launchpad.net/bugs/1493576 - -Reference ---------- - -For more information, see the reference: - -.. toctree:: - :maxdepth: 6 - - modules diff --git a/doc/source/reference/deprecation-policy.rst b/doc/source/reference/deprecation-policy.rst deleted file mode 100644 index c7e84fbb..00000000 --- a/doc/source/reference/deprecation-policy.rst +++ /dev/null @@ -1,32 +0,0 @@ -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.opendev.org/#/admin/groups/147,members - -3. Example: ``_ - - 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 index 92e93855..272b64ad 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -1,8 +1,8 @@ +========= Reference ========= .. toctree:: - :maxdepth: 1 + :maxdepth: 6 - api/index - deprecation-policy + api/modules diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 3c54920b..32510e67 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -6,3 +6,4 @@ :maxdepth: 2 shell + python-api diff --git a/doc/source/user/python-api.rst b/doc/source/user/python-api.rst new file mode 100644 index 00000000..b01e07f1 --- /dev/null +++ b/doc/source/user/python-api.rst @@ -0,0 +1,104 @@ +================================== + The :mod:`novaclient` Python API +================================== + +.. module:: novaclient + :synopsis: A client for the OpenStack Nova API. + :noindex: + +.. currentmodule:: novaclient + +Usage +----- + +First create a client instance with your credentials:: + + >>> from novaclient import client + >>> nova = client.Client(VERSION, USERNAME, PASSWORD, PROJECT_ID, AUTH_URL) + +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:: + + >>> from keystoneauth1 import loading + >>> from keystoneauth1 import session + >>> from novaclient import client + >>> loader = loading.get_plugin_loader('password') + >>> auth = loader.load_from_options(auth_url=AUTH_URL, + ... username=USERNAME, + ... password=PASSWORD, + ... project_id=PROJECT_ID) + >>> sess = session.Session(auth=auth) + >>> nova = client.Client(VERSION, session=sess) + +If you have PROJECT_NAME instead of a PROJECT_ID, use the project_name +parameter. Similarly, if your cloud uses keystone v3 and you have a DOMAIN_NAME +or DOMAIN_ID, provide it as `user_domain_(name|id)` and if you are using a +PROJECT_NAME also provide the domain information as `project_domain_(name|id)`. + +novaclient adds 'python-novaclient' and its version to the user-agent string +that keystoneauth produces. If you are creating an application using novaclient +and want to register a name and version in the user-agent string, pass those +to the Session:: + + >>> sess = session.Session( + ... auth=auth, app_name'nodepool', app_version'1.2.3') + +If you are making a library that consumes novaclient but is not an end-user +application, you can append a (name, version) tuple to the session's +`additional_user_agent` property:: + + >>> sess = session.Session(auth=auth) + >>> sess.additional_user_agent.append(('shade', '1.2.3')) + +For more information on this keystoneauth API, see +:keystoneauth-doc:`Using Sessions `. + +It is also possible to use an instance as a context manager in which case +there will be a session kept alive for the duration of the with statement:: + + >>> from novaclient import client + >>> with client.Client(VERSION, USERNAME, PASSWORD, + ... PROJECT_ID, AUTH_URL) as nova: + ... nova.servers.list() + ... nova.flavors.list() + ... + +It is also possible to have a permanent (process-long) connection pool, +by passing a connection_pool=True:: + + >>> from novaclient import client + >>> nova = client.Client(VERSION, USERNAME, PASSWORD, PROJECT_ID, + ... AUTH_URL, connection_pool=True) + +Then call methods on its managers:: + + >>> nova.servers.list() + [] + + >>> nova.flavors.list() + [, + , + , + , + , + , + ] + + >>> fl = nova.flavors.find(ram=512) + >>> nova.servers.create("my-server", flavor=fl) + + +.. warning:: Direct initialization of ``novaclient.v2.client.Client`` object + can cause you to "shoot yourself in the foot". See launchpad bug-report + `1493576`_ for more details. + +.. _1493576: https://launchpad.net/bugs/1493576 + +Reference +--------- + +See :doc:`the module reference `. diff --git a/doc/source/user/shell.rst b/doc/source/user/shell.rst index 882bb756..465b0fb4 100644 --- a/doc/source/user/shell.rst +++ b/doc/source/user/shell.rst @@ -87,12 +87,4 @@ From there, all shell commands take the form:: Run :program:`nova help` to get a full list of all possible commands, and run :program:`nova help ` to get detailed help for that command. -Reference ---------- - -For more information, see the reference: - -.. toctree:: - :maxdepth: 2 - - /cli/nova +For more information, see :doc:`the command reference `. -- cgit v1.2.1