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:
melissaml
Nguyen Hai
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
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ['sphinx.ext.autodoc',
|
||||
extensions = ['sphinxcontrib.apidoc',
|
||||
'sphinx.ext.viewcode',
|
||||
]
|
||||
|
||||
|
|
@ -22,9 +22,15 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
|
|||
|
||||
wsme_protocols = ['restjson']
|
||||
|
||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||
# text edit cycles.
|
||||
# execute "export SPHINX_DEBUG=1" in your terminal to disable
|
||||
# sphinxcontrib.apidoc options
|
||||
apidoc_module_dir = '../../ironic_inspector_client'
|
||||
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.
|
||||
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
|
||||
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:
|
||||
|
||||
|
|
@ -23,16 +23,21 @@ requested, the server assumes the maximum it's supported.
|
|||
|
||||
Two constants are exposed for convenience:
|
||||
|
||||
* :py:const:`ironic_inspector_client.v1.DEFAULT_API_VERSION`
|
||||
* :py:const:`ironic_inspector_client.v1.MAX_API_VERSION`
|
||||
* :py:const:`ironic_inspector_client.DEFAULT_API_VERSION`
|
||||
* :py:const:`ironic_inspector_client.MAX_API_VERSION`
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. 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
|
||||
|
|
|
|||
|
|
@ -13,3 +13,7 @@
|
|||
|
||||
from .v1 import ClientV1, DEFAULT_API_VERSION, MAX_API_VERSION # 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.
|
||||
|
||||
:param uuid: node UUID or name
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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.
|
||||
"""
|
||||
if not isinstance(uuid, six.string_types):
|
||||
|
|
@ -110,9 +111,10 @@ class ClientV1(http.BaseClient):
|
|||
this request will return error response with 404 code.
|
||||
|
||||
:param uuid: node UUID or name.
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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: TypeError if uuid is not a string.
|
||||
"""
|
||||
|
|
@ -133,9 +135,10 @@ class ClientV1(http.BaseClient):
|
|||
|
||||
:param marker: pagination maker, UUID or None
|
||||
:param limit: pagination limit, int or None
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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.
|
||||
:return: a list of status dictionaries with the keys:
|
||||
|
||||
|
|
@ -164,9 +167,10 @@ class ClientV1(http.BaseClient):
|
|||
"""Get introspection status for a node.
|
||||
|
||||
:param uuid: node UUID or name.
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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.
|
||||
:return: dictionary with the keys:
|
||||
|
||||
|
|
@ -192,10 +196,12 @@ class ClientV1(http.BaseClient):
|
|||
:param retry_interval: sleep interval between retries.
|
||||
:param max_retries: maximum number of retries.
|
||||
:param sleep_function: function used for sleeping between retries.
|
||||
:raises: :py:class:`.WaitTimeoutError` on timeout
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.WaitTimeoutError` on
|
||||
timeout
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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.
|
||||
: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 raw: whether to return raw binary data or parsed JSON data
|
||||
:returns: bytes or a dict depending on the 'raw' argument
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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: TypeError if uuid is not a string
|
||||
"""
|
||||
|
|
@ -256,9 +263,10 @@ class ClientV1(http.BaseClient):
|
|||
"""Abort running introspection for a node.
|
||||
|
||||
:param uuid: node UUID or name.
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
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: 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 description: optional rule description
|
||||
:returns: rule representation
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
reported from a server
|
||||
: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):
|
||||
raise TypeError(
|
||||
|
|
@ -389,9 +398,10 @@ class RulesAPI(object):
|
|||
:param json_rule: rule information as a dict with keys matching
|
||||
arguments of :py:meth:`RulesAPI.create`.
|
||||
:returns: rule representation
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
reported from a server
|
||||
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||
requested api_version is not supported
|
||||
"""
|
||||
return self._request('post', '/rules', json=json_rule).json()
|
||||
|
||||
|
|
@ -400,9 +410,10 @@ class RulesAPI(object):
|
|||
|
||||
:returns: list of short rule representations (uuid, description
|
||||
and links)
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
reported from a server
|
||||
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||
requested api_version is not supported
|
||||
"""
|
||||
return self._request('get', '/rules').json()['rules']
|
||||
|
||||
|
|
@ -411,9 +422,10 @@ class RulesAPI(object):
|
|||
|
||||
:param uuid: rule UUID
|
||||
:returns: rule representation
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
reported from a server
|
||||
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||
requested api_version is not supported
|
||||
"""
|
||||
if not isinstance(uuid, six.string_types):
|
||||
raise TypeError(
|
||||
|
|
@ -424,9 +436,10 @@ class RulesAPI(object):
|
|||
"""Delete an introspection rule.
|
||||
|
||||
:param uuid: rule UUID
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
reported from a server
|
||||
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||
requested api_version is not supported
|
||||
"""
|
||||
if not isinstance(uuid, six.string_types):
|
||||
raise TypeError(
|
||||
|
|
@ -436,8 +449,9 @@ class RulesAPI(object):
|
|||
def delete_all(self):
|
||||
"""Delete all introspection rules.
|
||||
|
||||
:raises: :py:class:`.ClientError` on error reported from a server
|
||||
:raises: :py:class:`.VersionNotSupported` if requested api_version
|
||||
is not supported
|
||||
:raises: :py:class:`ironic_inspector_client.ClientError` on error
|
||||
reported from a server
|
||||
:raises: :py:class:`ironic_inspector_client.VersionNotSupported` if
|
||||
requested api_version is not supported
|
||||
"""
|
||||
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_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]
|
||||
cli =
|
||||
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
|
||||
mock>=2.0.0 # BSD
|
||||
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
|
||||
python-openstackclient>=3.12.0 # Apache-2.0
|
||||
|
|
|
|||
17
tox.ini
17
tox.ini
|
|
@ -35,18 +35,27 @@ commands = {[testenv:functional]commands}
|
|||
|
||||
[testenv:venv]
|
||||
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}
|
||||
|
||||
[testenv:releasenotes]
|
||||
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
|
||||
|
||||
[testenv:docs]
|
||||
basepython = python3
|
||||
setenv = PYTHONHASHSEED=0
|
||||
sitepackages = False
|
||||
commands =
|
||||
python setup.py build_sphinx
|
||||
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 -W -b html doc/source doc/build/html
|
||||
|
||||
[flake8]
|
||||
max-complexity=15
|
||||
|
|
|
|||
Loading…
Reference in New Issue