Improve docs rendering

Author: Tom-Willemsen

src/genie_python/genie.py

@@ -177,7 +177,7 @@ def get_block_units(block_name: str) -> str | None:
     Args:
         block_name: name of the block
 
-    Returns
+    Returns:
         string: units of the block
     """
     return _genie_api.get_block_units(block_name)
@@ -1162,10 +1162,10 @@ def get_time_since_begin(get_timedelta: bool = False) -> float | datetime.timede
         get_timedelta (bool): If true return the value as a datetime object,
             otherwise return seconds (defaults to false)
 
-    Returns
-        integer: the time since start in seconds if get_datetime is False,
-            or timedelta, the time since begin as a datetime.timedelta object
-            (Year-Month-Day  Hour:Minute:Second) if get_datetime is True
+    Returns:
+        integer: The time since start in seconds if get_datetime is False,
+        or timedelta, the time since begin as a datetime.timedelta object
+        (Year-Month-Day  Hour:Minute:Second) if get_datetime is True
     """
     assert _genie_api.dae is not None
     return _genie_api.dae.get_time_since_begin(get_timedelta)
@@ -1460,7 +1460,7 @@ def load_script(name: str, check_script: bool = True, warnings_as_error: bool =
 
     Args:
         name (string): the name of the file to load. If this is not a
-            full path the file is assumed to be in C:\\scripts
+            full path, the file is assumed to be in `C:\\\\scripts`
         check_script: When True run the script checker on the script;
             False otherwise (default True)
         warnings_as_error: When true throw an exception on a warning;
@@ -1665,7 +1665,9 @@ def change_tables(
 ) -> None:
     """
     Load the wiring, detector and/or spectra tables.
+
     Checks that the file paths are valid, throws exception if not.
+
     Args:
         wiring (string, optional): the filename of the wiring table file
         detector (string, optional): the filename of the detector table file
@@ -1729,7 +1731,7 @@ def change_sync(source: str) -> None:
          'muon cerenkov',
          'muon ms',
          'isis (first ts1)'
-    )
+        )
     """
     assert _genie_api.dae is not None
     _genie_api.dae.change_sync(source)
@@ -1765,7 +1767,7 @@ def change_tcb(
     Change the time channel boundaries.
     If None is specified for low, high or step then the values are left unchanged.
 
-    Args
+    Args:
         low (float, optional): the lower limit. Default is no change from the current value.
         high (float, optional): the upper limit. Default is no change from the current value.
         step (float,optional): the step size. Default is no change from the current value.
@@ -2314,7 +2316,8 @@ def change_beamline_par(name: str, value: PVValue) -> None:
 def send_sms(phone_num: str, message: str) -> None:
     """
     Sends an SMS message to a phone number.
-    If you are sending to messages to the same number often consider using g.alerts.send()
+
+    If you are sending to messages to the same number often, consider using `g.alerts.send()`
 
     Args:
         phone_num (string): the phone number to send the SMS to
@@ -2497,6 +2500,7 @@ def set_dae_simulation_mode(mode: bool, skip_required_runstates: bool = False) -
 def get_dae_simulation_mode() -> bool:
     """
     Gets the DAE simulation mode.
+
     Returns:
         True if the DAE is in simulation mode, False otherwise.
     """
@@ -2523,7 +2527,7 @@ def load(name: str) -> None:
 @usercommand
 @log_command_and_handle_exception
 def get_wiring_table() -> str | None:
-    """Gets the current wiring table path"
+    """Gets the current wiring table path.
 
     Returns:
             The file path of the current wiring table.
@@ -2535,7 +2539,7 @@ def get_wiring_table() -> str | None:
 @usercommand
 @log_command_and_handle_exception
 def get_spectra_table() -> str | None:
-    """Gets the current spectra table path"
+    """Gets the current spectra table path.
 
     Returns:
             The file path of the current spectra table.
@@ -2547,7 +2551,7 @@ def get_spectra_table() -> str | None:
 @usercommand
 @log_command_and_handle_exception
 def get_detector_table() -> str | None:
-    """Gets the current detector table path"
+    """Gets the current detector table path.
 
     Returns:
             The file path of the current detector table.
@@ -2571,6 +2575,9 @@ def get_dae_autosave_freq() -> int | None:
 def set_dae_autosave_freq(freq: int) -> None:
     """
     Sets the ICP autosave frequency (Frames).
+
+    Args:
+        freq: The autosave frequency in frames.
     """
     assert _genie_api.dae is not None
     return _genie_api.dae.set_autosave_freq(freq)

src/genie_python/genie_advanced.py

@@ -34,7 +34,7 @@ def get_manager_mode() -> bool:
     Returns whether you are in manager mode or not.
 
     Returns:
-        manager_mode (Bool): Manager mode on or off.
+        manager_mode (bool): Manager mode on or off.
 
     """
 
@@ -47,9 +47,8 @@ def assert_in_manager_mode() -> None:
     """
     Checks that the user is in manager mode so can use advanced functions.
 
-    Args:
-
-    Returns:
+    Raises:
+        RuntimeError: If the user is not in manager mode.
 
     """
 
@@ -67,7 +66,6 @@ def motor_in_set_mode(pv_name: str) -> Iterator[None]:
     Args:
         pv_name: pv of motor on which to set the mode
 
-    Returns:
     """
 
     if not __api.pv_exists(pv_name):
@@ -101,8 +99,6 @@ def redefine_motor_position(name: str, value: float | int) -> None:
         name: Name of the motor. e.g MTR0101
         value: The new value of Move Abs.
 
-    Returns:
-
     """
 
     assert_in_manager_mode()
@@ -144,7 +140,7 @@ def pv_exists(pv: str, is_local: bool = False) -> bool:
     """
     Check if PV exists.
 
-    Params:
+    Args:
         pv (str): The address of the PV
         is_local (bool, optional): is it a local PV i.e. needs prefix adding
     """
@@ -160,7 +156,7 @@ def wait_for_pv(
     """
     Wait until a PV has reached a given value.
 
-    Params:
+    Args:
         pv (str): The address of the PV
         value: The value to wait for
         maxwait (int, optional): The maximum time to wait for in seconds
@@ -305,7 +301,8 @@ def open_plot_window(
 ) -> None:
     """
     Open the plot window in a locally running client
-    (even if this is called in a standalone genie_python)
+    (even if this is called in a standalone genie_python).
+
     Args:
         is_primary: True to open primary plotting window; False open secondaty window
         host: host to open plot from; Default None is localhost

src/genie_python/genie_alerts.py

@@ -167,6 +167,7 @@ def _print_block(block: str, only_if_enabled: bool = False) -> None:
 def status(block: str | None = None, all: bool = False) -> None:
     """
     Prints the emails and mobiles used for alerts and the current status of specified block.
+
     Args:
         block (string): The block to print information about
         all (bool): If True information about all the blocks is printed