Edit docstring in run_tardis (tardis-sn#1723)

* edit docstring in run_tardis

* [build docs]

tardis/base.py

@@ -1,4 +1,4 @@
-# functions that are important for the general usage of TARDIS
+# Functions that are important for the general usage of TARDIS.
 
 import logging
 
@@ -16,27 +16,46 @@ def run_tardis(
     specific=None,
 ):
     """
-    This function is one of the core functions to run TARDIS from a given
-    config object.
+    Run TARDIS from a given config object.
 
-    It will return a model object containing
+    It will return a model object containing the TARDIS Simulation.
 
     Parameters
     ----------
     config : str or dict or tardis.io.config_reader.Configuration
         filename of configuration yaml file or dictionary or TARDIS Configuration object
-    atom_data : str or tardis.atomic.AtomData
-        if atom_data is a string it is interpreted as a path to a file storing
-        the atomic data. Atomic data to use for this TARDIS simulation. If set to None, the
-        atomic data will be loaded according to keywords set in the configuration
-        [default=None]
-    virtual_packet_logging : bool
-        option to enable virtual packet logging
-        [default=False]
+    atom_data : str or tardis.atomic.AtomData, optional
+        If atom_data is a string it is interpreted as a path to a file storing
+        the atomic data. Atomic data to use for this TARDIS simulation. If set to None (i.e. default),
+        the atomic data will be loaded according to keywords set in the configuration
+    packet_source : class, optional
+        A custom packet source class or a child class of `tardis.montecarlo.packet_source`
+        used to override the TARDIS `BasePacketSource` class.
+    simulation_callbacks : list of lists, default: `[]`, optional
+        Set of callbacks to call at the end of every iteration of the Simulation.
+        The format of the lists should look like:
+        [[callback1, callback_arg1], [callback2, callback_arg2], ...],
+        where the callback function signature should look like:
+        callback_function(simulation, extra_arg1, ...)
+    virtual_packet_logging : bool, default: False, optional
+        Option to enable virtual packet logging.
+    log_level : {'NOTSET', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'}, default: None, optional
+        Set the level of the TARDIS logger (follows native python logging framework log levels).
+        Use this parameter to override the `log_level` specified in the configuration file.
+        The default value `None` means that the `log_level` specified in the configuration file will be used.
+    specific : bool, default: None, optional
+        Allows to set specific logging levels, overriding the value in the configuration file.
+        If True, only show the log messages from a particular log level, set by `log_level`.
+        If False, the logger shows log messages belonging to the level set and all levels above it in severity.
+        The default value None means that the `specific` specified in the configuration file will be used.
 
     Returns
     -------
-    Simulation
+    tardis.simulation.Simulation
+
+    Notes
+    -----
+    Please see the `logging tutorial <https://tardis-sn.github.io/tardis/io/optional/logging_configuration.html>`_ to know more about `log_level` and `specific` options.
     """
     from tardis.io.logger.logger import logging_state
     from tardis.io.config_reader import Configuration