From b9206a5349724a179cf90fbd7f09555cfbbd7fd1 Mon Sep 17 00:00:00 2001 From: Michael Johnson Date: Mon, 14 Feb 2022 18:50:55 +0000 Subject: Fix api index and module index This patch fixes the index and module index for the osprofiler documentation home page. It also updates the documents tox environments to use a docs requirements.txt Change-Id: I880f1c28232a299f50ea9ccc2178f1444efb9a41 --- .gitignore | 3 +++ doc/requirements.txt | 7 +++++++ doc/source/conf.py | 8 ++++++++ doc/source/index.rst | 6 ++++++ lower-constraints.txt | 1 + osprofiler/drivers/base.py | 13 +++++-------- osprofiler/drivers/elasticsearch_driver.py | 13 +++++-------- osprofiler/drivers/loginsight.py | 5 ++--- osprofiler/drivers/messaging.py | 3 +-- osprofiler/drivers/mongodb.py | 13 +++++-------- osprofiler/drivers/redis_driver.py | 13 +++++-------- test-requirements.txt | 7 +------ tox.ini | 16 ++++++++++++++-- 13 files changed, 63 insertions(+), 45 deletions(-) create mode 100644 doc/requirements.txt diff --git a/.gitignore b/.gitignore index f044aaf..e2ef07f 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,9 @@ cover .pydevproject .idea +# Docs generated +doc/source/contributor/modules + # reno build releasenotes/build RELEASENOTES.rst diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..10f37cc --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,7 @@ +docutils>=0.14 # OSI-Approved Open Source, Public Domain +openstackdocstheme>=2.2.1 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD +sphinxcontrib-apidoc>=0.2.1 # BSD + +# Build release notes +reno>=3.1.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index f904f7f..a9a2e79 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -49,6 +49,7 @@ extensions = [ 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'openstackdocstheme', + 'sphinxcontrib.apidoc', ] # openstackdocstheme options @@ -130,3 +131,10 @@ texinfo_documents = [ 'Miscellaneous' ), ] + +apidoc_output_dir = 'contributor/modules' +apidoc_module_dir = '../../osprofiler' +apidoc_excluded_paths = [ + 'hacking', + 'tests', +] diff --git a/doc/source/index.rst b/doc/source/index.rst index 01c8b3e..6e60523 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,12 @@ reasons (for example in isolating cross-project performance issues). user/index +.. toctree:: + :hidden: + + contributor/modules/modules + + .. rubric:: Indices and tables * :ref:`genindex` diff --git a/lower-constraints.txt b/lower-constraints.txt index 994e394..aafaad0 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -1,5 +1,6 @@ coverage===4.0 ddt===1.0.1 +docutils==0.14 dulwich===0.15.0 elasticsearch===2.0.0 importlib_metadata==1.7.0 diff --git a/osprofiler/drivers/base.py b/osprofiler/drivers/base.py index 99b37b1..f717d69 100644 --- a/osprofiler/drivers/base.py +++ b/osprofiler/drivers/base.py @@ -87,15 +87,12 @@ class Driver(object): :param info: Contains information about trace element. In payload dict there are always 3 ids: "base_id" - uuid that is common for all notifications - related to one trace. Used to simplify - retrieving of all trace elements from - the backend. + related to one trace. Used to simplify retrieving of all + trace elements from the backend. "parent_id" - uuid of parent element in trace "trace_id" - uuid of current element in trace - With parent_id and trace_id it's quite simple to build tree of trace elements, which simplify analyze of trace. - """ raise NotImplementedError("{0}: This method is either not supported " "or has to be overridden".format( @@ -119,9 +116,9 @@ class Driver(object): """Query all traces from the storage. :param fields: Set of trace fields to return. Defaults to 'base_id' - and 'timestamp' - :return List of traces, where each trace is a dictionary containing - at least `base_id` and `timestamp`. + and 'timestamp' + :returns: List of traces, where each trace is a dictionary containing + at least `base_id` and `timestamp`. """ raise NotImplementedError("{0}: This method is either not supported " "or has to be overridden".format( diff --git a/osprofiler/drivers/elasticsearch_driver.py b/osprofiler/drivers/elasticsearch_driver.py index d4a6b3d..da9be17 100644 --- a/osprofiler/drivers/elasticsearch_driver.py +++ b/osprofiler/drivers/elasticsearch_driver.py @@ -58,15 +58,12 @@ class ElasticsearchDriver(base.Driver): :param info: Contains information about trace element. In payload dict there are always 3 ids: "base_id" - uuid that is common for all notifications - related to one trace. Used to simplify - retrieving of all trace elements from - Elasticsearch. + related to one trace. Used to simplify retrieving of all + trace elements from Elasticsearch. "parent_id" - uuid of parent element in trace "trace_id" - uuid of current element in trace - With parent_id and trace_id it's quite simple to build tree of trace elements, which simplify analyze of trace. - """ info = info.copy() @@ -111,9 +108,9 @@ class ElasticsearchDriver(base.Driver): """Query all traces from the storage. :param fields: Set of trace fields to return. Defaults to 'base_id' - and 'timestamp' - :return List of traces, where each trace is a dictionary containing - at least `base_id` and `timestamp`. + and 'timestamp' + :returns: List of traces, where each trace is a dictionary containing + at least `base_id` and `timestamp`. """ query = {"match_all": {}} fields = set(fields or self.default_trace_fields) diff --git a/osprofiler/drivers/loginsight.py b/osprofiler/drivers/loginsight.py index f59518b..31fe1ee 100644 --- a/osprofiler/drivers/loginsight.py +++ b/osprofiler/drivers/loginsight.py @@ -39,13 +39,12 @@ class LogInsightDriver(base.Driver): is 3.3. The connection string to initialize the driver should be of the format: - loginsight://:@ + loginsight://:@ If the username or password contains the character ':' or '@', it must be escaped using URL encoding. For example, the connection string to connect to Log Insight server at 10.1.2.3 using username "osprofiler" and password - "p@ssword" is: - loginsight://osprofiler:p%40ssword@10.1.2.3 + "p@ssword" is: loginsight://osprofiler:p%40ssword@10.1.2.3 """ def __init__( self, connection_str, project=None, service=None, host=None, diff --git a/osprofiler/drivers/messaging.py b/osprofiler/drivers/messaging.py index 3381cf6..c7fbd12 100644 --- a/osprofiler/drivers/messaging.py +++ b/osprofiler/drivers/messaging.py @@ -83,10 +83,9 @@ class Messaging(base.Driver): :param info: Contains information about trace element. In payload dict there are always 3 ids: "base_id" - uuid that is common for all notifications - related to one trace. + related to one trace. "parent_id" - uuid of parent element in trace "trace_id" - uuid of current element in trace - With parent_id and trace_id it's quite simple to build tree of trace elements, which simplify analyze of trace. diff --git a/osprofiler/drivers/mongodb.py b/osprofiler/drivers/mongodb.py index 86119e4..fdd4a46 100644 --- a/osprofiler/drivers/mongodb.py +++ b/osprofiler/drivers/mongodb.py @@ -45,15 +45,12 @@ class MongoDB(base.Driver): :param info: Contains information about trace element. In payload dict there are always 3 ids: "base_id" - uuid that is common for all notifications - related to one trace. Used to simplify - retrieving of all trace elements from - MongoDB. + related to one trace. Used to simplify retrieving of all + trace elements from MongoDB. "parent_id" - uuid of parent element in trace "trace_id" - uuid of current element in trace - With parent_id and trace_id it's quite simple to build tree of trace elements, which simplify analyze of trace. - """ data = info.copy() data["project"] = self.project @@ -76,9 +73,9 @@ class MongoDB(base.Driver): """Query all traces from the storage. :param fields: Set of trace fields to return. Defaults to 'base_id' - and 'timestamp' - :return List of traces, where each trace is a dictionary containing - at least `base_id` and `timestamp`. + and 'timestamp' + :returns: List of traces, where each trace is a dictionary containing + at least `base_id` and `timestamp`. """ fields = set(fields or self.default_trace_fields) ids = self.db.profiler.find({}).distinct("base_id") diff --git a/osprofiler/drivers/redis_driver.py b/osprofiler/drivers/redis_driver.py index 48436cf..ba7a121 100644 --- a/osprofiler/drivers/redis_driver.py +++ b/osprofiler/drivers/redis_driver.py @@ -61,15 +61,12 @@ class Redis(base.Driver): :param info: Contains information about trace element. In payload dict there are always 3 ids: "base_id" - uuid that is common for all notifications - related to one trace. Used to simplify - retrieving of all trace elements from - Redis. + related to one trace. Used to simplify retrieving of all + trace elements from Redis. "parent_id" - uuid of parent element in trace "trace_id" - uuid of current element in trace - With parent_id and trace_id it's quite simple to build tree of trace elements, which simplify analyze of trace. - """ data = info.copy() data["project"] = self.project @@ -94,9 +91,9 @@ class Redis(base.Driver): """Query all traces from the storage. :param fields: Set of trace fields to return. Defaults to 'base_id' - and 'timestamp' - :return List of traces, where each trace is a dictionary containing - at least `base_id` and `timestamp`. + and 'timestamp' + :returns: List of traces, where each trace is a dictionary containing + at least `base_id` and `timestamp`. """ fields = set(fields or self.default_trace_fields) diff --git a/test-requirements.txt b/test-requirements.txt index a2ca153..3e1bbd8 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -5,9 +5,7 @@ coverage>=4.0 # Apache-2.0 ddt>=1.0.1 # MIT stestr>=2.0.0 # Apache-2.0 testtools>=2.2.0 # MIT - -openstackdocstheme>=2.2.1 # Apache-2.0 -sphinx>=2.0.0,!=2.1.0 # BSD +docutils>=0.14 # OSI-Approved Open Source, Public Domain # Bandit security code scanner bandit>=1.6.0,<1.7.0 # Apache-2.0 @@ -20,9 +18,6 @@ elasticsearch>=2.0.0,<3.0.0 # Apache-2.0 # Redis python client redis>=2.10.0 # MIT -# Build release notes -reno>=3.1.0 # Apache-2.0 - # For Jaeger Tracing jaeger-client>=3.8.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index e261868..4fb34f4 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -minversion = 3.1.0 +minversion = 3.18.0 # Needed to create ChangeLog for docs building skipsdist = False envlist = py3,pep8 @@ -52,7 +52,13 @@ commands = coverage xml -o cover/coverage.xml [testenv:docs] +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/requirements.txt + -r{toxinidir}/doc/requirements.txt +allowlist_externals = rm commands = + rm -rf doc/build api-guide/build api-ref/build doc/source/contributor/modules sphinx-build -W --keep-going -b html -d doc/build/doctrees doc/source doc/build/html [testenv:bandit] @@ -83,7 +89,13 @@ extension = paths = ./osprofiler/hacking [testenv:releasenotes] -commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/doc/requirements.txt +allowlist_externals = rm +commands = + rm -rf releasenotes/build + sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html [testenv:lower-constraints] deps = -- cgit v1.2.1