Edit docstring formatting and spacing (#1403)

clearml/automation/scheduler.py

@@ -580,23 +580,58 @@ class TaskScheduler(BaseScheduler):
 
         Examples:
 
-        Launch every 15 minutes
+        Launch every 15 minutes:
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', minute=15)
-        Launch every 1 hour
+
+        Launch every 1 hour:
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', hour=1)
-        Launch every 1 hour at hour:30 minutes (i.e. 1:30, 2:30 etc.)
+
+        Launch every 1 hour at hour:30 minutes (i.e. 1:30, 2:30 etc.):
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', hour=1, minute=30)
-        Launch every day at 22:30 (10:30 pm)
+
+        Launch every day at 22:30 (10:30 pm):
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', minute=30, hour=22, day=1)
-        Launch every other day at 7:30 (7:30 am)
+
+        Launch every other day at 7:30 (7:30 am):
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', minute=30, hour=7, day=2)
-        Launch every Saturday at 8:30am (notice `day=0`)
+
+        Launch every Saturday at 8:30am (notice `day=0`):
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', minute=30, hour=8, day=0, weekdays=['saturday'])
-        Launch every 2 hours on the weekends Saturday/Sunday (notice `day` is not passed)
+
+        Launch every 2 hours on the weekends Saturday/Sunday (notice `day` is not passed):
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', hour=2, weekdays=['saturday', 'sunday'])
-        Launch once a month at the 5th of each month
+
+        Launch once a month at the 5th of each month:
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', month=1, day=5)
-        Launch once a year on March 4th
+
+        Launch once a year on March 4th:
+
+        .. code-block:: py
+
             add_task(schedule_task_id='1235', queue='default', year=1, month=3, day=4)
 
         :param schedule_task_id: ID of Task to be cloned and scheduled for execution

clearml/backend_interface/task/task.py

@@ -2467,12 +2467,18 @@ class Task(IdObjectBase, AccessMixin, SetupUploadMixin):
         """
         Force the adding of a package to the requirements list. If ``package_version`` is None, use the
         installed package version, if found.
-        Example: Task.add_requirements('tensorflow', '2.4.0')
+
-        Example: Task.add_requirements('tensorflow', '>=2.4')
+        Example: ``Task.add_requirements('tensorflow', '2.4.0')``
-        Example: Task.add_requirements('tensorflow') -> use the installed tensorflow version
+
-        Example: Task.add_requirements('tensorflow', '') -> no version limit
+        Example: ``Task.add_requirements('tensorflow', '>=2.4')``
-        Alternatively, you can add all requirements from a file.
+
-        Example: Task.add_requirements('/path/to/your/project/requirements.txt')
+        Example: ``Task.add_requirements('tensorflow')`` -> use the installed tensorflow version
+
+        Example: ``Task.add_requirements('tensorflow', '')`` -> no version limit
+
+        Alternatively, you can add all requirements from a file:
+
+        Example: ``Task.add_requirements('/path/to/your/project/requirements.txt')``
 
         .. note::
             Task.add_requirements does not directly modify the task's requirements. Instead, it improves the accuracy

clearml/task.py

@@ -448,19 +448,18 @@ class Task(_Task):
           - ``True`` - Automatically create resource monitoring plots. (default)
           - ``False`` - Do not automatically create.
           - Class Type - Create ResourceMonitor object of the specified class type.
-          - dict - Dictionary of kwargs to be passed to the ResourceMonitor instance.
+          - dict - Dictionary of kwargs to be passed to the ResourceMonitor instance. The keys can be:
-              The keys can be:
               - `report_start_sec` OR `first_report_sec` OR `seconds_from_start` - Maximum number of seconds
-                  to wait for scalar/plot reporting before defaulting
+                to wait for scalar/plot reporting before defaulting
-                  to machine statistics reporting based on seconds from experiment start time
+                to machine statistics reporting based on seconds from experiment start time
               - `wait_for_first_iteration_to_start_sec` - Set the initial time (seconds) to wait for iteration
-                   reporting to be used as x-axis for the resource monitoring,
+                reporting to be used as x-axis for the resource monitoring,
-                   if timeout exceeds then reverts to `seconds_from_start`
+                if timeout exceeds then reverts to `seconds_from_start`
               - `max_wait_for_first_iteration_to_start_sec` - Set the maximum time (seconds) to allow the resource
-                  monitoring to revert back to iteration reporting x-axis after starting to report `seconds_from_start`
+                monitoring to revert back to iteration reporting x-axis after starting to report `seconds_from_start`
               - `report_mem_used_per_process` OR `report_global_mem_used` - Compatibility feature,
-                  report memory usage for the entire machine
+                report memory usage for the entire machine.
-                  default (false), report only on the running process and its sub-processes
+                Default (false), report only on the running process and its sub-processes
 
         :param auto_connect_streams: Control the automatic logging of stdout and stderr.
             The values are:
@@ -468,16 +467,16 @@ class Task(_Task):
           - ``True`` - Automatically connect (default)
           -  ``False`` - Do not automatically connect
           - A dictionary - In addition to a boolean, you can use a dictionary for fined grained control of stdout and
-              stderr. The dictionary keys are 'stdout' , 'stderr' and 'logging', the values are booleans.
+            stderr. The dictionary keys are 'stdout' , 'stderr' and 'logging', the values are booleans.
-              Keys missing from the dictionary default to ``False``, and an empty dictionary defaults to ``False``.
+            Keys missing from the dictionary default to ``False``, and an empty dictionary defaults to ``False``.
-              Notice, the default behaviour is logging stdout/stderr. The `logging` module is logged as a by product
+            Notice, the default behaviour is logging stdout/stderr. The `logging` module is logged as a by product
-              of the stderr logging
+            of the stderr logging
 
-              For example:
+            For example:
 
-              .. code-block:: py
+            .. code-block:: py
 
-                 auto_connect_streams={'stdout': True, 'stderr': True, 'logging': False}
+               auto_connect_streams={'stdout': True, 'stderr': True, 'logging': False}
 
         :param deferred_init: (default: False) Wait for Task to be fully initialized (regular behaviour).
             ** BETA feature! use with care **.
@@ -488,8 +487,8 @@ class Task(_Task):
             Default behaviour can be controlled with: ``CLEARML_DEFERRED_TASK_INIT=1``. Notes:
 
           - Any access to the returned proxy `Task` object will essentially wait for the `Task.init` to be completed.
-              For example: `print(task.name)` will wait for `Task.init` to complete in the
+            For example: `print(task.name)` will wait for `Task.init` to complete in the
-              background and then return the `name` property of the task original object
+            background and then return the `name` property of the task original object
           - Before `Task.init` completes in the background, auto-magic logging (console/metric) might be missed
           - If running via an agent, this argument is ignored, and Task init is called synchronously (default)
 
@@ -954,10 +953,10 @@ class Task(_Task):
         :return: If wait is False, this method will return None.
             If no endpoint could be found while waiting, this method returns None.
             Otherwise, it returns a dictionary containing the following values:
-            - endpoint - raw endpoint. One might need to authenticate in order to use this endpoint
+          - endpoint - raw endpoint. One might need to authenticate in order to use this endpoint
-            - browser_endpoint - endpoint to be used in browser. Authentication will be handled via the browser
+          - browser_endpoint - endpoint to be used in browser. Authentication will be handled via the browser
-            - port - the port exposed by the application
+          - port - the port exposed by the application
-            - protocol - the protocol used by the endpoint
+          - protocol - the protocol used by the endpoint
         """
         Session.verify_feature_set("advanced")
         if protocol not in self._external_endpoint_port_map.keys():
@@ -1059,10 +1058,10 @@ class Task(_Task):
 
         :return: If no endpoint could be found while waiting, this method returns None.
             If a protocol has been specified, it returns a dictionary containing the following values:
-            - endpoint - raw endpoint. One might need to authenticate in order to use this endpoint
+          - endpoint - raw endpoint. One might need to authenticate in order to use this endpoint
-            - browser_endpoint - endpoint to be used in browser. Authentication will be handled via the browser
+          - browser_endpoint - endpoint to be used in browser. Authentication will be handled via the browser
-            - port - the port exposed by the application
+          - port - the port exposed by the application
-            - protocol - the protocol used by the endpoint
+          - protocol - the protocol used by the endpoint
             If not protocol is specified, it returns a list of dictionaries containing the values above,
             for each protocol requested and waited
         """