Fix docstrings errors and warnings

BrunoCoimbra · mambelli · commit e8d1922ecbe4 · 2022-09-15T11:59:52.000-05:00
diff --git a/doc/source/release_notes/release_notes_1.6.rst b/doc/source/release_notes/release_notes_1.6.rst
@@ -22,7 +22,7 @@ Enhancements:
 
 
 Full list of commits since version 1.6.1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `c4c7681 <https://github.com/HEPCloud/decisionengine/commit/c4c7681ccb391acdca1da79a972f2cbf8b31b87a>`_:   Updated de-query-tool w/ cherry pick of fixes from latest version of PR#332
 
diff --git a/doc/source/release_notes/release_notes_1.7.rst b/doc/source/release_notes/release_notes_1.7.rst
@@ -18,7 +18,7 @@ Patch level (bug fix) release.
 
 
 Issues fixed in this release
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 Bugs fixed
@@ -31,7 +31,7 @@ Enhancements:
 
 
 Full list of commits since version 1.7.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `606e1e9f <https://github.com/HEPCloud/decisionengine/commit/606e1e9fdd56b17e51fef92da679bfbb90485747>`_:   Merge pull request #585 from vitodb/fix/1.7/vito_port_PR527
 
diff --git a/doc/source/release_notes/release_notes_2.0.rst b/doc/source/release_notes/release_notes_2.0.rst
@@ -8,7 +8,7 @@ Patch level (bug fix) release.
 
 
 Issues fixed in this release
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Bugs fixed
 
@@ -26,7 +26,7 @@ Enhancements:
 
 
 Full list of commits since version 2.0.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 `b5e56ab8 <https://github.com/HEPCloud/decisionengine/commit/b5e56ab8701266e890fed6e9ca4baff49c131c86>`_:   Remove signal handler.
 
diff --git a/src/decisionengine/framework/dataspace/datablock.py b/src/decisionengine/framework/dataspace/datablock.py
@@ -278,18 +278,25 @@ def store_taskmanager(self, taskmanager_name, taskmanager_id):
     def get_taskmanager(self, taskmanager_name, taskmanager_id=None):
         """
         Retrieve TaskManager
-        :type taskmanager_name: :obj:`string`
-        :arg taskmanager_name: name of taskmanager to retrieve
-        :type taskmanager_id: :obj:`string`
-        :arg taskmanager_id: id of taskmanager to retrieve
-        :rtype: :obj: `dict`
+
+        Args:
+            taskmanager_name (str): Name of the TaskManager
+            taskmanager_id (str, optional): ID of the TaskManager to retrieve. Defaults to None.
+        
+        Returns:
+            dict: TaskManager information
 
         The dictionary returned looks like :
-        {'datestamp': datetime.datetime(2017, 12, 20, 17, 37, 17, 503210,
-                      tzinfo=psycopg2.tz.FixedOffsetTimezone(offset=-360, name=None)),
-         'sequence_id': 135L,
-         'name': 'AWS_Calculations',
-         'taskmanager_id': '77B16EB5-C79E-45B0-B1B1-37E846692E1D'}
+
+        .. code-block:: python
+
+            {
+                'datestamp': datetime.datetime(2017, 12, 20, 17, 37, 17, 503210,
+                            tzinfo=psycopg2.tz.FixedOffsetTimezone(offset=-360, name=None)),
+                'sequence_id': 135L,
+                'name': 'AWS_Calculations',
+                'taskmanager_id': '77B16EB5-C79E-45B0-B1B1-37E846692E1D'
+            }
         """
         return self.dataspace.get_taskmanager(taskmanager_name, taskmanager_id)
 
diff --git a/src/decisionengine/framework/dataspace/datasources/sqlalchemy_ds/datasource_api.py b/src/decisionengine/framework/dataspace/datasources/sqlalchemy_ds/datasource_api.py
@@ -32,22 +32,24 @@ class SQLAlchemyDS(ds.DataSource):
     """
     A DecisionEngine data source via the SQL Alchemy ORM
 
-    {
-      "dataspace": {
-        "datasource": {
-          "module": "decisionengine.framework.dataspace.datasources.sqlalchemy_ds",
-          "name": "SQLAlchemyDS",
-          "params": {
-            "pool_size": 5,
-            "max_overflow": 10,
-            "timeout": 30,
-
-            # url is mandatory, but any `engine` keyword is accepted here.
-            "url": "dialect[+driver]://user:password@host/dbname"
-          }
+    .. code-block:: python
+
+        {
+            "dataspace": {
+                "datasource": {
+                    "module": "decisionengine.framework.dataspace.datasources.sqlalchemy_ds",
+                    "name": "SQLAlchemyDS",
+                    "params": {
+                        "pool_size": 5,
+                        "max_overflow": 10,
+                        "timeout": 30,
+
+                        # url is mandatory, but any `engine` keyword is accepted here.
+                        "url": "dialect[+driver]://user:password@host/dbname"
+                    }
+                }
+            }
         }
-      }
-    }
 
     Exceptions should be caught and logged by the caller.
     """
diff --git a/src/decisionengine/framework/logicengine/FactLookup.py b/src/decisionengine/framework/logicengine/FactLookup.py
@@ -20,23 +20,28 @@ class FactLookup:
 
     As an example, consider the following configuration:
 
-      facts: {
-        should_publish: "(True)",
-      },
-      rules: {
-        publish_1: {
-          expression: "should_publish",
-          facts: ["should_publish"]
-        },
-        publish_2: {
-          expression: "should_publish",
-          actions: ["go_to_press"]
-          facts: ["should_publish"]
+    .. code-block:: json
+
+        {
+            "facts": {
+                "should_publish": "(True)"
+            },
+            "rules": {
+                "publish_1": {
+                    "expression": "should_publish",
+                    "facts": ["should_publish"]
+                },
+                "publish_2": {
+                    "expression": "should_publish",
+                    "actions": ["go_to_press"],
+                    "facts": ["should_publish"]
+                },
+                "retract": {
+                    "expression": "not should_publish",
+                    "facts": ["should_retract"]
+                }
+            }
         }
-        retract: {
-          expression: "not should_publish",
-          facts: ["should_retract"]
-      }
 
     In the above, the first fact to be evaluated will always be the
     top-level facts (i.e. those not encapsulated by the 'rules' table).
diff --git a/src/decisionengine/framework/logicengine/LogicEngine.py b/src/decisionengine/framework/logicengine/LogicEngine.py
@@ -91,15 +91,20 @@ def _create_facts_dataframe(self, newfacts):
         ['rule_name', 'fact_name', fact_value']
 
         facts dict format:
-        'newfacts': {
-            'publish_glidein_requests': {
-                'allow_hpc_new': True,
-                'allow_foo': True
-            },
-            'dummy_rule': {
-                'dummy_new_fact': True
+
+        .. code-block:: json
+
+            {
+                "newfacts": {
+                    "publish_glidein_requests": {
+                        "allow_hpc_new": true,
+                        "allow_foo": true
+                    },
+                    "dummy_rule": {
+                        "dummy_new_fact": true
+                    }
+                }
             }
-        }
         """
         self.logger.debug("in LE::_create_facts_dataframe")
         # Extract new facts from le_result
diff --git a/src/decisionengine/framework/taskmanager/LatestMessages.py b/src/decisionengine/framework/taskmanager/LatestMessages.py
@@ -11,14 +11,16 @@
 
 The LatestMessages class is intended to be used as a context manager (e.g.):
 
-  with LatestMessages(queues, broker_url) as messages:
-      while some_predicate():
-          msgs = messages.consume()
-          if not msgs:
-              continue
-
-          for routing_key, msg in msgs.items():
-              ...
+.. code-block:: python
+
+    with LatestMessages(queues, broker_url) as messages:
+        while some_predicate():
+            msgs = messages.consume()
+            if not msgs:
+                continue
+
+            for routing_key, msg in msgs.items():
+                ...
 
 Upon exiting the the context, a LatestMessage object will no longer
 listen for any messages.
diff --git a/src/decisionengine/framework/util/countdown.py b/src/decisionengine/framework/util/countdown.py
@@ -12,6 +12,8 @@ class Countdown:
     should not take longer than a specified period of time.  This is done
     by occasionally querying the 'time_left' attribute (e.g.):
 
+    .. code-block:: python
+
         countdown = Countdown(wait_up_to=10)
         for p in processes:
             with countdown:
diff --git a/src/decisionengine/framework/util/reaper.py b/src/decisionengine/framework/util/reaper.py
@@ -6,11 +6,16 @@
 """
 A stand-alone script purges data in database older than specified
 in configuration. Configuration file has to have this bit added:
-   {
-     "dataspace" : { "retention_interval_in_days" : 365,
-                      "datasource" :  { ... }
-                   }
-    }
+
+    .. code-block:: json
+
+        {
+            "dataspace" : {
+                "retention_interval_in_days" : 365,
+                "datasource" :  {}
+            }
+        }
+
 Can be used in a cron job.
 """
 import os
