Follow the new PTI for document build
For compliance with the Project Testing Interface as described in: https://governance.openstack.org/tc/reference/project-testing-interface.html http://lists.openstack.org/pipermail/openstack-dev/2017-December/125710.html http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html Some docstrings had to be updated to avoid ambiguous references to exceptions that are available both through ironic_inspector_client and ironic_inspector_client.v1. Co-Authored-By: Nguyen Hai <nguyentrihai93@gmail.com> Co-Authored-By: Dmitry Tantsur <dtantsur@redhat.com> Change-Id: Ib24cd87aedce77f3f0fa49245408ee83e7a9eef0
This commit is contained in:
parent
f5537093db
commit
519475f94a
|
@ -0,0 +1,4 @@
|
||||||
|
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
|
||||||
|
openstackdocstheme>=1.18.1 # Apache-2.0
|
||||||
|
reno>=2.5.0 # Apache-2.0
|
||||||
|
sphinxcontrib-apidoc>=0.2.0 # BSD
|
|
@ -5,7 +5,7 @@
|
||||||
|
|
||||||
# Add any Sphinx extension module names here, as strings. They can be
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||||
extensions = ['sphinx.ext.autodoc',
|
extensions = ['sphinxcontrib.apidoc',
|
||||||
'sphinx.ext.viewcode',
|
'sphinx.ext.viewcode',
|
||||||
]
|
]
|
||||||
|
|
||||||
|
@ -22,9 +22,15 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
|
||||||
|
|
||||||
wsme_protocols = ['restjson']
|
wsme_protocols = ['restjson']
|
||||||
|
|
||||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
# sphinxcontrib.apidoc options
|
||||||
# text edit cycles.
|
apidoc_module_dir = '../../ironic_inspector_client'
|
||||||
# execute "export SPHINX_DEBUG=1" in your terminal to disable
|
apidoc_output_dir = 'reference/api'
|
||||||
|
apidoc_excluded_paths = [
|
||||||
|
'test/*',
|
||||||
|
'test',
|
||||||
|
'common/i18n*',
|
||||||
|
'shell*']
|
||||||
|
apidoc_separate_modules = True
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
templates_path = ['_templates']
|
templates_path = ['_templates']
|
||||||
|
|
|
@ -8,7 +8,7 @@ To use Python API first create a ``ClientV1`` object::
|
||||||
|
|
||||||
This code creates a client with API version *1.0* and a given `Keystone
|
This code creates a client with API version *1.0* and a given `Keystone
|
||||||
session`_. The service URL is fetched from the service catalog in this case.
|
session`_. The service URL is fetched from the service catalog in this case.
|
||||||
See :py:class:`ironic_inspector_client.v1.ClientV1` documentation for details.
|
See :py:class:`ironic_inspector_client.ClientV1` documentation for details.
|
||||||
|
|
||||||
.. _api-versioning:
|
.. _api-versioning:
|
||||||
|
|
||||||
|
@ -23,16 +23,21 @@ requested, the server assumes the maximum it's supported.
|
||||||
|
|
||||||
Two constants are exposed for convenience:
|
Two constants are exposed for convenience:
|
||||||
|
|
||||||
* :py:const:`ironic_inspector_client.v1.DEFAULT_API_VERSION`
|
* :py:const:`ironic_inspector_client.DEFAULT_API_VERSION`
|
||||||
* :py:const:`ironic_inspector_client.v1.MAX_API_VERSION`
|
* :py:const:`ironic_inspector_client.MAX_API_VERSION`
|
||||||
|
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 2
|
||||||
|
|
||||||
api/autoindex
|
api/ironic_inspector_client
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
api/modules
|
||||||
|
|
||||||
.. _Keystone session: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
|
.. _Keystone session: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
|
||||||
|
|
|
@ -13,3 +13,7 @@
|
||||||
|
|
||||||
from .v1 import ClientV1, DEFAULT_API_VERSION, MAX_API_VERSION # noqa
|
from .v1 import ClientV1, DEFAULT_API_VERSION, MAX_API_VERSION # noqa
|
||||||
from .common.http import ClientError, EndpointNotFound, VersionNotSupported # noqa
|
from .common.http import ClientError, EndpointNotFound, VersionNotSupported # noqa
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = ['ClientV1', 'DEFAULT_API_VERSION', 'MAX_API_VERSION',
|
||||||
|
'ClientError', 'EndpointNotFound', 'VersionNotSupported']
|
||||||
|
|
|
@ -92,9 +92,10 @@ class ClientV1(http.BaseClient):
|
||||||
"""Start introspection for a node.
|
"""Start introspection for a node.
|
||||||
|
|
||||||
:param uuid: node UUID or name
|
:param uuid: node UUID or name
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
"""
|
"""
|
||||||
if not isinstance(uuid, six.string_types):
|
if not isinstance(uuid, six.string_types):
|
||||||
|
@ -110,9 +111,10 @@ class ClientV1(http.BaseClient):
|
||||||
this request will return error response with 404 code.
|
this request will return error response with 404 code.
|
||||||
|
|
||||||
:param uuid: node UUID or name.
|
:param uuid: node UUID or name.
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
:raises: TypeError if uuid is not a string.
|
:raises: TypeError if uuid is not a string.
|
||||||
"""
|
"""
|
||||||
|
@ -133,9 +135,10 @@ class ClientV1(http.BaseClient):
|
||||||
|
|
||||||
:param marker: pagination maker, UUID or None
|
:param marker: pagination maker, UUID or None
|
||||||
:param limit: pagination limit, int or None
|
:param limit: pagination limit, int or None
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
:return: a list of status dictionaries with the keys:
|
:return: a list of status dictionaries with the keys:
|
||||||
|
|
||||||
|
@ -164,9 +167,10 @@ class ClientV1(http.BaseClient):
|
||||||
"""Get introspection status for a node.
|
"""Get introspection status for a node.
|
||||||
|
|
||||||
:param uuid: node UUID or name.
|
:param uuid: node UUID or name.
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported`
|
||||||
|
if requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
:return: dictionary with the keys:
|
:return: dictionary with the keys:
|
||||||
|
|
||||||
|
@ -192,10 +196,12 @@ class ClientV1(http.BaseClient):
|
||||||
:param retry_interval: sleep interval between retries.
|
:param retry_interval: sleep interval between retries.
|
||||||
:param max_retries: maximum number of retries.
|
:param max_retries: maximum number of retries.
|
||||||
:param sleep_function: function used for sleeping between retries.
|
:param sleep_function: function used for sleeping between retries.
|
||||||
:raises: :py:class:`.WaitTimeoutError` on timeout
|
:raises: :py:class:`ironic_inspector_client.WaitTimeoutError` on
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
timeout
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
is not supported
|
reported from a server
|
||||||
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
:return: dictionary UUID -> status (the same as in get_status).
|
:return: dictionary UUID -> status (the same as in get_status).
|
||||||
"""
|
"""
|
||||||
|
@ -236,9 +242,10 @@ class ClientV1(http.BaseClient):
|
||||||
:param uuid: node UUID or name.
|
:param uuid: node UUID or name.
|
||||||
:param raw: whether to return raw binary data or parsed JSON data
|
:param raw: whether to return raw binary data or parsed JSON data
|
||||||
:returns: bytes or a dict depending on the 'raw' argument
|
:returns: bytes or a dict depending on the 'raw' argument
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
:raises: TypeError if uuid is not a string
|
:raises: TypeError if uuid is not a string
|
||||||
"""
|
"""
|
||||||
|
@ -256,9 +263,10 @@ class ClientV1(http.BaseClient):
|
||||||
"""Abort running introspection for a node.
|
"""Abort running introspection for a node.
|
||||||
|
|
||||||
:param uuid: node UUID or name.
|
:param uuid: node UUID or name.
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
:raises: *requests* library exception on connection problems.
|
:raises: *requests* library exception on connection problems.
|
||||||
:raises: TypeError if uuid is not a string.
|
:raises: TypeError if uuid is not a string.
|
||||||
"""
|
"""
|
||||||
|
@ -365,9 +373,10 @@ class RulesAPI(object):
|
||||||
:param uuid: rule UUID, will be generated if not specified
|
:param uuid: rule UUID, will be generated if not specified
|
||||||
:param description: optional rule description
|
:param description: optional rule description
|
||||||
:returns: rule representation
|
:returns: rule representation
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
"""
|
"""
|
||||||
if uuid is not None and not isinstance(uuid, six.string_types):
|
if uuid is not None and not isinstance(uuid, six.string_types):
|
||||||
raise TypeError(
|
raise TypeError(
|
||||||
|
@ -389,9 +398,10 @@ class RulesAPI(object):
|
||||||
:param json_rule: rule information as a dict with keys matching
|
:param json_rule: rule information as a dict with keys matching
|
||||||
arguments of :py:meth:`RulesAPI.create`.
|
arguments of :py:meth:`RulesAPI.create`.
|
||||||
:returns: rule representation
|
:returns: rule representation
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
"""
|
"""
|
||||||
return self._request('post', '/rules', json=json_rule).json()
|
return self._request('post', '/rules', json=json_rule).json()
|
||||||
|
|
||||||
|
@ -400,9 +410,10 @@ class RulesAPI(object):
|
||||||
|
|
||||||
:returns: list of short rule representations (uuid, description
|
:returns: list of short rule representations (uuid, description
|
||||||
and links)
|
and links)
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
"""
|
"""
|
||||||
return self._request('get', '/rules').json()['rules']
|
return self._request('get', '/rules').json()['rules']
|
||||||
|
|
||||||
|
@ -411,9 +422,10 @@ class RulesAPI(object):
|
||||||
|
|
||||||
:param uuid: rule UUID
|
:param uuid: rule UUID
|
||||||
:returns: rule representation
|
:returns: rule representation
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
"""
|
"""
|
||||||
if not isinstance(uuid, six.string_types):
|
if not isinstance(uuid, six.string_types):
|
||||||
raise TypeError(
|
raise TypeError(
|
||||||
|
@ -424,9 +436,10 @@ class RulesAPI(object):
|
||||||
"""Delete an introspection rule.
|
"""Delete an introspection rule.
|
||||||
|
|
||||||
:param uuid: rule UUID
|
:param uuid: rule UUID
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
"""
|
"""
|
||||||
if not isinstance(uuid, six.string_types):
|
if not isinstance(uuid, six.string_types):
|
||||||
raise TypeError(
|
raise TypeError(
|
||||||
|
@ -436,8 +449,9 @@ class RulesAPI(object):
|
||||||
def delete_all(self):
|
def delete_all(self):
|
||||||
"""Delete all introspection rules.
|
"""Delete all introspection rules.
|
||||||
|
|
||||||
:raises: :py:class:`.ClientError` on error reported from a server
|
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
reported from a server
|
||||||
is not supported
|
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||||
|
requested api_version is not supported
|
||||||
"""
|
"""
|
||||||
self._request('delete', '/rules')
|
self._request('delete', '/rules')
|
||||||
|
|
15
setup.cfg
15
setup.cfg
|
@ -37,21 +37,6 @@ openstack.baremetal_introspection.v1 =
|
||||||
baremetal_introspection_interface_list = ironic_inspector_client.shell:InterfaceListCommand
|
baremetal_introspection_interface_list = ironic_inspector_client.shell:InterfaceListCommand
|
||||||
baremetal_introspection_interface_show = ironic_inspector_client.shell:InterfaceShowCommand
|
baremetal_introspection_interface_show = ironic_inspector_client.shell:InterfaceShowCommand
|
||||||
|
|
||||||
[pbr]
|
|
||||||
autodoc_index_modules = True
|
|
||||||
autodoc_exclude_modules =
|
|
||||||
ironic_inspector_client.test.*
|
|
||||||
ironic_inspector_client.common.i18n
|
|
||||||
ironic_inspector_client.shell
|
|
||||||
warnerrors = True
|
|
||||||
api_doc_dir = reference/api
|
|
||||||
|
|
||||||
[build_sphinx]
|
|
||||||
all_files = 1
|
|
||||||
build-dir = doc/build
|
|
||||||
source-dir = doc/source
|
|
||||||
warning-is-error = 1
|
|
||||||
|
|
||||||
[extras]
|
[extras]
|
||||||
cli =
|
cli =
|
||||||
python-openstackclient>=3.12.0 # Apache-2.0
|
python-openstackclient>=3.12.0 # Apache-2.0
|
||||||
|
|
|
@ -7,8 +7,5 @@ fixtures>=3.0.0 # Apache-2.0/BSD
|
||||||
hacking>=1.0.0,<1.1.0 # Apache-2.0
|
hacking>=1.0.0,<1.1.0 # Apache-2.0
|
||||||
mock>=2.0.0 # BSD
|
mock>=2.0.0 # BSD
|
||||||
requests-mock>=1.2.0 # Apache-2.0
|
requests-mock>=1.2.0 # Apache-2.0
|
||||||
sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
|
|
||||||
openstackdocstheme>=1.18.1 # Apache-2.0
|
|
||||||
reno>=2.5.0 # Apache-2.0
|
|
||||||
oslo.concurrency>=3.25.0 # Apache-2.0
|
oslo.concurrency>=3.25.0 # Apache-2.0
|
||||||
python-openstackclient>=3.12.0 # Apache-2.0
|
python-openstackclient>=3.12.0 # Apache-2.0
|
||||||
|
|
17
tox.ini
17
tox.ini
|
@ -35,18 +35,27 @@ commands = {[testenv:functional]commands}
|
||||||
|
|
||||||
[testenv:venv]
|
[testenv:venv]
|
||||||
basepython = python3
|
basepython = python3
|
||||||
|
deps =
|
||||||
|
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
|
||||||
|
-r{toxinidir}/requirements.txt
|
||||||
|
-r{toxinidir}/doc/requirements.txt
|
||||||
commands = {posargs}
|
commands = {posargs}
|
||||||
|
|
||||||
[testenv:releasenotes]
|
[testenv:releasenotes]
|
||||||
basepython = python3
|
basepython = python3
|
||||||
|
deps =
|
||||||
|
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
|
||||||
|
-r{toxinidir}/requirements.txt
|
||||||
|
-r{toxinidir}/doc/requirements.txt
|
||||||
commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
|
commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
|
||||||
|
|
||||||
[testenv:docs]
|
[testenv:docs]
|
||||||
basepython = python3
|
basepython = python3
|
||||||
setenv = PYTHONHASHSEED=0
|
deps =
|
||||||
sitepackages = False
|
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
|
||||||
commands =
|
-r{toxinidir}/requirements.txt
|
||||||
python setup.py build_sphinx
|
-r{toxinidir}/doc/requirements.txt
|
||||||
|
commands = sphinx-build -W -b html doc/source doc/build/html
|
||||||
|
|
||||||
[flake8]
|
[flake8]
|
||||||
max-complexity=15
|
max-complexity=15
|
||||||
|
|
Loading…
Reference in New Issue