Clean up built-in xtrigger docstrings

cylc/flow/xtriggers/wall_clock.py

@@ -19,11 +19,11 @@
 from time import time
 
 
-def wall_clock(trigger_time=None):
+def wall_clock(trigger_time: int) -> bool:
     """Return True after the desired wall clock time, False.
 
     Args:
-        trigger_time (int):
+        trigger_time:
             Trigger time as seconds since Unix epoch.
     """
     return time() > trigger_time

cylc/flow/xtriggers/workflow_state.py

@@ -35,6 +35,7 @@ def workflow_state(
     message: Optional[str] = None,
     cylc_run_dir: Optional[str] = None
 ) -> Tuple[bool, Optional[Dict[str, Optional[str]]]]:
+    # NOTE: docstring must be valid rst as this is included in the docs
     """Connect to a workflow DB and query the requested task state.
 
     * Reports satisfied only if the remote workflow state has been achieved.
@@ -55,6 +56,7 @@ def workflow_state(
             The task status required for this xtrigger to be satisfied.
         message:
             The custom task output required for this xtrigger to be satisfied.
+
             .. note::
 
                This cannot be specified in conjunction with ``status``.
@@ -72,7 +74,7 @@ def workflow_state(
         tuple: (satisfied, results)
 
         satisfied:
-            True if ``satisfied`` else ``False``.
+            ``True`` if ``satisfied`` else ``False``.
         results:
             Dictionary containing the args / kwargs which were provided
             to this xtrigger.

cylc/flow/xtriggers/xrandom.py

@@ -23,9 +23,10 @@
 
 
 def xrandom(percent, secs=0, _=None):
+    # NOTE: docstring must be valid rst as this is included in the docs
     """Random xtrigger, with configurable sleep and percent success.
 
-    Sleep for ``sec`` seconds, and report satisfied with ~``percent``
+    Sleep for ``sec`` seconds, and report satisfied with ~ ``percent``
     likelihood.
 
     The ``_`` argument is not used in the function code, but can be used to
@@ -43,28 +44,37 @@ def xrandom(percent, secs=0, _=None):
     Examples:
         If the percent is zero, it returns that the trigger condition was
         not satisfied, and an empty dictionary.
-        >>> xrandom(0, 0)
-        (False, {})
+
+        .. code-block:: python
+
+           >>> xrandom(0, 0)
+           (False, {})
 
         If the percent is not zero, but the random percent success is not met,
         then it also returns that the trigger condition was not satisfied,
         and an empty dictionary.
-        >>> import sys
-        >>> mocked_random = lambda: 0.3
-        >>> sys.modules[__name__].random = mocked_random
-        >>> xrandom(15.5, 0)
-        (False, {})
+
+        .. code-block:: python
+
+           >>> import sys
+           >>> mocked_random = lambda: 0.3
+           >>> sys.modules[__name__].random = mocked_random
+           >>> xrandom(15.5, 0)
+           (False, {})
 
         Finally, if the percent is not zero, and the random percent success is
         met, then it returns that the trigger condition was satisfied, and a
         dictionary containing random color and size as result.
-        >>> import sys
-        >>> mocked_random = lambda: 0.9
-        >>> sys.modules[__name__].random = mocked_random
-        >>> mocked_randint = lambda x, y: 1
-        >>> sys.modules[__name__].randint = mocked_randint
-        >>> xrandom(99.99, 0)
-        (True, {'COLOR': 'orange', 'SIZE': 'small'})
+
+        .. code-block:: python
+
+           >>> import sys
+           >>> mocked_random = lambda: 0.9
+           >>> sys.modules[__name__].random = mocked_random
+           >>> mocked_randint = lambda x, y: 1
+           >>> sys.modules[__name__].randint = mocked_randint
+           >>> xrandom(99.99, 0)
+           (True, {'COLOR': 'orange', 'SIZE': 'small'})
 
     Returns:
         tuple: (satisfied, results)