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

@@ -40,6 +40,9 @@ cover
 .pydevproject
 .idea
 
+# Docs generated
+doc/source/contributor/modules
+
 # reno build
 releasenotes/build
 RELEASENOTES.rst

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

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',
+]

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`

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

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
+                      related to one trace. Used to simplify retrieving of all
-                                  retrieving of all trace elements from
+                      trace elements from the backend.
-                                  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'
+                       and 'timestamp'
-        :return List of traces, where each trace is a dictionary containing
+        :returns: List of traces, where each trace is a dictionary containing
-                at least `base_id` and `timestamp`.
+                  at least `base_id` and `timestamp`.
         """
         raise NotImplementedError("{0}: This method is either not supported "
                                   "or has to be overridden".format(

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
+                      related to one trace. Used to simplify retrieving of all
-                                  retrieving of all trace elements from
+                      trace elements from Elasticsearch.
-                                  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'
+                       and 'timestamp'
-        :return List of traces, where each trace is a dictionary containing
+        :returns: List of traces, where each trace is a dictionary containing
-                at least `base_id` and `timestamp`.
+                  at least `base_id` and `timestamp`.
         """
         query = {"match_all": {}}
         fields = set(fields or self.default_trace_fields)

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://<username>:<password>@<loginsight-host>
+    loginsight://<username>:<password>@<loginsight-host>
 
     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:
+    "p@ssword" is: loginsight://osprofiler:p%40ssword@10.1.2.3
-        loginsight://osprofiler:p%40ssword@10.1.2.3
     """
     def __init__(
             self, connection_str, project=None, service=None, host=None,

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.
 

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
+                      related to one trace. Used to simplify retrieving of all
-                                  retrieving of all trace elements from
+                      trace elements from MongoDB.
-                                  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'
+                       and 'timestamp'
-        :return List of traces, where each trace is a dictionary containing
+        :returns: List of traces, where each trace is a dictionary containing
-                at least `base_id` and `timestamp`.
+                  at least `base_id` and `timestamp`.
         """
         fields = set(fields or self.default_trace_fields)
         ids = self.db.profiler.find({}).distinct("base_id")

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
+                      related to one trace. Used to simplify retrieving of all
-                                  retrieving of all trace elements from
+                      trace elements from Redis.
-                                  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'
+                       and 'timestamp'
-        :return List of traces, where each trace is a dictionary containing
+        :returns: List of traces, where each trace is a dictionary containing
-                at least `base_id` and `timestamp`.
+                  at least `base_id` and `timestamp`.
         """
         fields = set(fields or self.default_trace_fields)
 

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
-
+docutils>=0.14 # OSI-Approved Open Source, Public Domain
-openstackdocstheme>=2.2.1 # Apache-2.0
-sphinx>=2.0.0,!=2.1.0 # BSD
 
 # 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
 

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 =