Fix docstring warnings

disdrodb/l0/check_metadata.py

@@ -123,21 +123,23 @@ def identify_empty_metadata_keys(metadata_fpaths: list, keys: Union[str, list])
 
 def get_archive_metadata_key_value(disdrodb_dir: str, key: str, return_tuple: bool = True):
     """Return the values of a metadata key for all the archive.
+
     Parameters
     ----------
     disdrodb_dir : str
         Path to the disdrodb directory.
     key : str
         Metadata key.
     return_tuple : bool, optional
-        if True, returns a tuple of values with station, campaign and data source name (default is True)
-        if False, returns a list of values without station, campaign and data source name
+       If True, returns a tuple of values with station, campaign and data source name.
+       If False, returns a list of values without station, campaign and data source name.
+       The default is True.
+
     Returns
     -------
     list or tuple
         List or tuple of values of the metadata key.
     """
-
     list_metadata_paths = get_list_metadata(
         disdrodb_dir, data_sources=None, campaign_names=None, station_names=None, with_stations_data=False
     )

disdrodb/l0/check_readers.py

@@ -140,7 +140,6 @@ def check_all_readers() -> None:
     """Test all readers that have data samples and ground truth.
 
     Raises
-
     ------
     Exception
         If the reader validation has failed.

disdrodb/l0/l0_processing.py

@@ -351,31 +351,33 @@ def run_l0a(
     ----------
     raw_dir : str
         The directory path where all the raw content of a specific campaign is stored.
-        The path must have the following structure:
-            <...>/DISDRODB/Raw/<data_source>/<campaign_name>'.
+        The path must have the following structure: ``<...>/DISDRODB/Raw/<data_source>/<campaign_name>``.
         Inside the raw_dir directory, it is required to adopt the following structure:
-        - /data/<station_name>/<raw_files>
-        - /metadata/<station_name>.yaml
+
+            - /data/<station_name>/<raw_files>
+            - /metadata/<station_name>.yaml
+
         Important points:
-        - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
-        - The <campaign_name> must semantically match between:
-           - the raw_dir and processed_dir directory paths;
-           - with the key 'campaign_name' within the metadata YAML files.
-        - The campaign_name are expected to be UPPER CASE.
+            - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
+            - The campaign_name are expected to be UPPER CASE.
+            - The <campaign_name> must semantically match between:
+
+                - the raw_dir and processed_dir directory paths;
+                - with the key 'campaign_name' within the metadata YAML files.
+
     processed_dir : str
         The desired directory path for the processed DISDRODB L0A and L0B products.
-        The path should have the following structure:
-            <...>/DISDRODB/Processed/<data_source>/<campaign_name>'
+        The path should have the following structure: ``<...>/DISDRODB/Processed/<data_source>/<campaign_name>``
         For testing purpose, this function exceptionally accept also a directory path simply ending
         with <campaign_name> (i.e. /tmp/<campaign_name>).
     station_name : str
         Station name
     glob_patterns: str
-        Glob pattern to search data files in <raw_dir>/data/<station_name>
+        Glob pattern to search data files in ``<raw_dir>/data/<station_name>``
     column_names : list
         Columns names of the raw text file.
     reader_kwargs : dict
-         Pandas `read_csv` arguments to open the text file.
+        Pandas `read_csv` arguments to open the text file.
     df_sanitizer_fun : object, optional
         Sanitizer function to format the datafame into DISDRODB L0A standard.
     parallel : bool
@@ -484,21 +486,23 @@ def run_l0b(
     ----------
     raw_dir : str
         The directory path where all the raw content of a specific campaign is stored.
-        The path must have the following structure:
-            <...>/DISDRODB/Raw/<data_source>/<campaign_name>'.
+        The path must have the following structure: ``<...>/DISDRODB/Raw/<data_source>/<campaign_name>``.
         Inside the raw_dir directory, it is required to adopt the following structure:
-        - /data/<station_name>/<raw_files>
-        - /metadata/<station_name>.yaml
+
+            - /data/<station_name>/<raw_files>
+            - /metadata/<station_name>.yaml
+
         Important points:
-        - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
-        - The <campaign_name> must semantically match between:
-           - the raw_dir and processed_dir directory paths;
-           - with the key 'campaign_name' within the metadata YAML files.
-        - The campaign_name are expected to be UPPER CASE.
+
+            - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
+            - The campaign_name are expected to be UPPER CASE.
+            - The <campaign_name> must semantically match between:
+                - the raw_dir and processed_dir directory paths;
+                - with the key 'campaign_name' within the metadata YAML files.
+
     processed_dir : str
         The desired directory path for the processed DISDRODB L0A and L0B products.
-        The path should have the following structure:
-            <...>/DISDRODB/Processed/<data_source>/<campaign_name>'
+        The path should have the following structure: ``<...>/DISDRODB/Processed/<data_source>/<campaign_name>``.
         For testing purpose, this function exceptionally accept also a directory path simply ending
         with <campaign_name> (i.e. /tmp/<campaign_name>).
     station_name : str
@@ -618,29 +622,32 @@ def run_l0b_from_nc(
 
     Parameters
     ----------
+
     raw_dir : str
         The directory path where all the raw content of a specific campaign is stored.
-        The path must have the following structure:
-            <...>/DISDRODB/Raw/<data_source>/<campaign_name>'.
+        The path must have the following structure: ``<...>/DISDRODB/Raw/<data_source>/<campaign_name>``.
         Inside the raw_dir directory, it is required to adopt the following structure:
-        - /data/<station_name>/<raw_files>
-        - /metadata/<station_name>.yaml
+
+            - /data/<station_name>/<raw_files>
+            - /metadata/<station_name>.yaml
+
         Important points:
-        - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
-        - The <campaign_name> must semantically match between:
-           - the raw_dir and processed_dir directory paths;
-           - with the key 'campaign_name' within the metadata YAML files.
-        - The campaign_name are expected to be UPPER CASE.
+            - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
+            - The campaign_name are expected to be UPPER CASE.
+            - The <campaign_name> must semantically match between:
+
+                - the raw_dir and processed_dir directory paths;
+                - with the key 'campaign_name' within the metadata YAML files.
+
     processed_dir : str
         The desired directory path for the processed DISDRODB L0B products.
-        The path should have the following structure:
-            <...>/DISDRODB/Processed/<data_source>/<campaign_name>'
+        The path should have the following structure: ``<...>/DISDRODB/Processed/<data_source>/<campaign_name>``
         For testing purpose, this function exceptionally accept also a directory path simply ending
         with <campaign_name> (i.e. /tmp/<campaign_name>).
     station_name : str
         Station name
     glob_patterns: str
-        Glob pattern to search data files in <raw_dir>/data/<station_name>.
+        Glob pattern to search data files in ``<raw_dir>/data/<station_name>``.
         Example: glob_patterns = "*.nc"
     dict_names : dict
         Dictionary mapping raw netCDF variables/coordinates/dimension names
@@ -863,11 +870,11 @@ def run_disdrodb_l0_station(
     station_name : str
         Station name
     l0a_processing : bool
-      Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
-      The default is True.
+        Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
+        The default is True.
     l0b_processing : bool
-      Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.
-      The default is True.
+        Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.
+        The default is True.
     l0b_concat : bool
         Whether to concatenate all raw files into a single L0B netCDF file.
         If l0b_concat=True, all raw files will be saved into a single L0B netCDF file.
@@ -877,8 +884,8 @@ def run_disdrodb_l0_station(
         Whether to keep the L0A files after having generated the L0B netCDF products.
         The default is False.
     remove_l0b : bool
-         Whether to remove the L0B files after having concatenated all L0B netCDF files.
-         It takes places only if l0b_concat=True
+        Whether to remove the L0B files after having concatenated all L0B netCDF files.
+        It takes places only if l0b_concat=True
         The default is False.
     force : bool
         If True, overwrite existing data into destination directories.
@@ -1016,11 +1023,11 @@ def run_disdrodb_l0(
         Station names to process.
         The default is None
     l0a_processing : bool
-      Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
-      The default is True.
+        Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
+        The default is True.
     l0b_processing : bool
-      Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.
-      The default is True.
+        Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.
+        The default is True.
     l0b_concat : bool
         Whether to concatenate all raw files into a single L0B netCDF file.
         If l0b_concat=True, all raw files will be saved into a single L0B netCDF file.
@@ -1030,8 +1037,8 @@ def run_disdrodb_l0(
         Whether to keep the L0A files after having generated the L0B netCDF products.
         The default is False.
     remove_l0b : bool
-         Whether to remove the L0B files after having concatenated all L0B netCDF files.
-         It takes places only if l0b_concat = True
+        Whether to remove the L0B files after having concatenated all L0B netCDF files.
+        It takes places only if l0b_concat = True
         The default is False.
     force : bool
         If True, overwrite existing data into destination directories.

disdrodb/l0/l0_reader.py

@@ -381,21 +381,24 @@ def reader_generic_docstring():
     ----------
     raw_dir : str
         The directory path where all the raw content of a specific campaign is stored.
-        The path must have the following structure:
-            <...>/DISDRODB/Raw/<data_source>/<campaign_name>'.
+        The path must have the following structure <...>/DISDRODB/Raw/<data_source>/<campaign_name>'.
         Inside the raw_dir directory, it is required to adopt the following structure:
-        - /data/<station_name>/<raw_files>
-        - /metadata/<station_name>.yaml
+
+            - /data/<station_name>/<raw_files>
+            - /metadata/<station_name>.yaml
+
         Important points:
-        - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
-        - The <campaign_name> must semantically match between:
-           - the raw_dir and processed_dir directory paths;
-           - with the key 'campaign_name' within the metadata YAML files.
-        - The campaign_name are expected to be UPPER CASE.
+
+            - For each <station_name> there must be a corresponding YAML file in the metadata subfolder.
+            - The campaign_name are expected to be UPPER CASE.
+            - The <campaign_name> must semantically match between:
+
+                - the raw_dir and processed_dir directory paths;
+                - with the key 'campaign_name' within the metadata YAML files.
+
     processed_dir : str
         The desired directory path for the processed DISDRODB L0A and L0B products.
-        The path should have the following structure:
-            <...>/DISDRODB/Processed/<data_source>/<campaign_name>'
+        The path should have the following structure <...>/DISDRODB/Processed/<data_source>/<campaign_name>'
         For testing purpose, this function exceptionally accept also a directory path simply ending
         with <campaign_name> (i.e. /tmp/<campaign_name>).
     station_name : str

disdrodb/l0/scripts/run_disdrodb_l0.py

@@ -51,14 +51,16 @@ def run_disdrodb_l0(
     parallel: bool = True,
     debugging_mode: bool = False,
 ):
-    """Run the L0 processing of DISDRODB stations.
+    """
+    Run the L0 processing of DISDRODB stations.
 
     This function enable to launch the processing of many DISDRODB stations with a single command.
     From the list of all available DISDRODB stations, it runs the processing of the
     stations matching the provided data_sources, campaign_names and station_names.
 
     Parameters
     ----------
+
     disdrodb_dir : str
         Base directory of DISDRODB
         Format: <...>/DISDRODB
@@ -75,11 +77,11 @@ def run_disdrodb_l0(
         Station names.
         To specify multiple stations, write i.e.: --station_names 'station1 station2'
     l0a_processing : bool
-      Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
-      The default is True.
+        Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
+        The default is True.
     l0b_processing : bool
-      Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.
-      The default is True.
+        Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.
+        The default is True.
     l0b_concat : bool
         Whether to concatenate all raw files into a single L0B netCDF file.
         If l0b_concat=True, all raw files will be saved into a single L0B netCDF file.

disdrodb/l0/scripts/run_disdrodb_l0_station.py

@@ -69,12 +69,11 @@ def run_disdrodb_l0_station(
     station_name : str \n
         Station name \n
     l0a_processing : bool
-      Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
-      The default is True.\n
+        Whether to launch processing to generate L0A Apache Parquet file(s) from raw data.
+        The default is True.\n
     l0b_processing : bool \n
-      Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.\n
-      The default is True.\n
-
+        Whether to launch processing to generate L0B netCDF4 file(s) from L0A data.\n
+        he default is True.\n
     l0b_concat : bool \n
         Whether to concatenate all raw files into a single L0B netCDF file.\n
         If l0b_concat=True, all raw files will be saved into a single L0B netCDF file.\n

disdrodb/l0/scripts/run_disdrodb_l0a.py

@@ -44,14 +44,16 @@ def run_disdrodb_l0a(
     parallel: bool = True,
     debugging_mode: bool = False,
 ):
-    """Run the L0A processing of DISDRODB stations.
+    """
+    Run the L0A processing of DISDRODB stations.
 
     This function enable to launch the processing of many DISDRODB stations with a single command.
-    From the list of all available DISDRODB stations, it runs the processing of the
-    stations matching the provided data_sources, campaign_names and station_names.
+    From the list of all available DISDRODB stations, it runs the processing
+    of the stations matching the provided data_sources, campaign_names and station_names.
 
     Parameters
     ----------
+
     disdrodb_dir : str
         Base directory of DISDRODB
         Format: <...>/DISDRODB

disdrodb/l0/scripts/run_disdrodb_l0b.py

@@ -44,14 +44,16 @@ def run_disdrodb_l0b(
     parallel: bool = True,
     debugging_mode: bool = False,
 ):
-    """Run the L0B processing of DISDRODB stations.
+    """
+    Run the L0B processing of DISDRODB stations.
 
     This function enable to launch the processing of many DISDRODB stations with a single command.
     From the list of all available DISDRODB stations, it runs the processing of the
     stations matching the provided data_sources, campaign_names and station_names.
 
     Parameters
     ----------
+
     disdrodb_dir : str
         Base directory of DISDRODB
         Format: <...>/DISDRODB

docs/requirements.txt

@@ -34,5 +34,6 @@ requests-mock==1.10.0
 requests==2.28.2
 sphinx==5.1.1
 sphinx_rtd_theme==1.0.0
+sphinx-mdinclude==0.5.3
 tqdm==4.65.0
 disdrodb==0.0.17

docs/source/authors.rst

@@ -1,3 +1,4 @@
-.. _list_authors:
+List of contributors
+=====================
 
 .. mdinclude:: ../../AUTHORS.md

docs/source/conf.py

@@ -46,6 +46,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
     "nbsphinx",
+    "sphinx_mdinclude",
 ]