Improve docstring for documentation API

Author: ghiggi

MANIFEST.in

@@ -2,7 +2,5 @@ prune .github
 prune data
 prune docs
 prune tutorials
-prune ci 
+prune ci
 prune disdrodb/tests
-
-

ci/environment.yml

@@ -9,7 +9,6 @@ dependencies:
   - donfig
   - requests
   - trollsift
-  - h5py
   - netcdf4
   - pyarrow
   - pandas

ci/environment_latest.yml

@@ -9,7 +9,6 @@ dependencies:
   - donfig
   - requests
   - trollsift
-  - h5py
   - netcdf4
   - pyarrow
   - pandas

disdrodb/_config.py

@@ -26,7 +26,7 @@
 
 
 def _get_disdrodb_default_configs():
-    """Retrieve the default DISDRODB settings from the .config_disdrodb.yml file."""
+    """Retrieve the default DISDRODB settings from the ``.config_disdrodb.yml`` file."""
     try:
         config_dict = read_disdrodb_configs()
         config_dict = {key: value for key, value in config_dict.items() if value is not None}

disdrodb/api/checks.py

@@ -67,7 +67,7 @@ def check_url(url: str) -> bool:
     Returns
     -------
     bool
-        True if url well formatted, False if not well formatted.
+        ``True`` if url well formatted, ``False`` if not well formatted.
     """
     regex = r"^(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)$"  # noqa: E501
 
@@ -87,14 +87,14 @@ def check_path_is_a_directory(dir_path, path_name=""):
 
 
 def check_directories_inside(dir_path):
-    """Check there are directories inside the specified dir_path."""
+    """Check there are directories inside the specified ``dir_path``."""
     dir_paths = os.listdir(dir_path)
     if len(dir_paths) == 0:
         raise ValueError(f"There are not directories within {dir_path}")
 
 
 def check_base_dir(base_dir: str):
-    """Raise an error if the path does not end with "DISDRODB"."""
+    """Raise an error if the path does not end with ``DISDRODB``."""
     base_dir = str(base_dir)  # convert Pathlib to string
     if not base_dir.endswith("DISDRODB"):
         raise ValueError(f"The path {base_dir} does not end with DISDRODB. Please check the path.")
@@ -114,7 +114,7 @@ def check_sensor_name(sensor_name: str, product: str = "L0A") -> None:
     Raises
     ------
     TypeError
-        Error if `sensor_name` is not a string.
+        Error if ``sensor_name`` is not a string.
     ValueError
         Error if the input sensor name has not been found in the list of available sensors.
     """
@@ -177,7 +177,7 @@ def check_station_dir(product, data_source, campaign_name, station_name, base_di
 
 
 def has_available_station_files(product, data_source, campaign_name, station_name, base_dir=None):
-    """Return True if data are available for the given product and station."""
+    """Return ``True`` if data are available for the given product and station."""
     station_dir = check_station_dir(
         product=product,
         base_dir=base_dir,
@@ -295,7 +295,7 @@ def check_issue_file(data_source, campaign_name, station_name, base_dir=None):
 
 
 def check_is_within_raw_directory(path):
-    """Check the path is within the DISDRODB 'Raw' directory."""
+    """Check the path is within the DISDRODB ``Raw`` directory."""
     components = infer_disdrodb_tree_path_components(path)
     if components[1] != "Raw":
         msg = f"{path} is not within the 'Raw' directory."
@@ -304,7 +304,7 @@ def check_is_within_raw_directory(path):
 
 
 def check_is_within_processed_directory(path):
-    """Check the path is within the DISDRODB 'Processed' directory."""
+    """Check the path is within the DISDRODB ``Processed`` directory."""
     components = infer_disdrodb_tree_path_components(path)
     if components[1] != "Processed":
         msg = f"{path} is not within the 'Processed' directory."
@@ -315,9 +315,9 @@ def check_is_within_processed_directory(path):
 def check_valid_campaign_dir(campaign_dir):
     """Check the validity of a campaign directory path.
 
-    Used to check validity of 'raw_dir' and 'processed_dir'.
+    Used to check validity of ``raw_dir`` and ``processed_dir``.
 
-    The path must represents this path */DISDRODB/<Raw or Processed>/<DATA_SOURCE>/<CAMPAIGN_NAME>
+    The path must be ``*/DISDRODB/<Raw/Processed>/<DATA_SOURCE>/<CAMPAIGN_NAME>``
     """
     last_component = os.path.basename(campaign_dir)
     tree_components = infer_disdrodb_tree_path_components(campaign_dir)
@@ -347,11 +347,16 @@ def check_raw_dir(raw_dir: str, station_name: str) -> None:
     """Check validity of raw_dir content.
 
     Steps:
-    1. Check that 'raw_dir' is a valid directory path
-    2. Check that 'raw_dir' follows the expect directory structure
-    3. Check that each station_name directory contains data
-    4. Check that for each station_name the mandatory metadata.yml is specified.
-    5. Check that for each station_name the mandatory issue.yml is specified.
+
+        1. Check that ``raw_dir`` is a valid directory path
+
+        2. Check that ``raw_dir`` follows the expect directory structure
+
+        3. Check that each ``station_name`` directory contains data
+
+        4. Check that for each station_name the mandatory ``metadata.yml`` is specified.
+
+        5. Check that for each station_name the mandatory ``issue.yml`` is specified.
 
     Parameters
     ----------
@@ -361,7 +366,7 @@ def check_raw_dir(raw_dir: str, station_name: str) -> None:
         Station name.
     verbose : bool, optional
         Whether to verbose the processing.
-        The default is False.
+        The default is ``False``.
 
     """
     # Ensure valid path format
@@ -415,12 +420,12 @@ def check_raw_dir(raw_dir: str, station_name: str) -> None:
 
 
 def check_processed_dir(processed_dir):
-    """Check input, format and validity of the 'processed_dir' directory path.
+    """Check input, format and validity of the ``processed_dir`` directory path.
 
     Parameters
     ----------
     processed_dir : str
-        Path to the campaign directory in the 'DISDRODB/Processed directory tree
+        Path to the campaign directory in the ``DISDRODB/Processed`` directory tree
 
     Returns
     -------

disdrodb/api/create_directories.py

@@ -59,7 +59,7 @@
 
 #### DISDRODB Products directories
 def _check_data_source_consistency(raw_dir: str, processed_dir: str) -> str:
-    """Check that 'raw_dir' and 'processed_dir' have same data_source.
+    """Check that ``raw_dir`` and ``processed_dir`` have same ``data_source``.
 
     Parameters
     ----------
@@ -71,12 +71,12 @@ def _check_data_source_consistency(raw_dir: str, processed_dir: str) -> str:
     Returns
     -------
     str
-        data_source in capital letter.
+        ``data_source`` in capital letter.
 
     Raises
     ------
     ValueError
-        Error if the data_source of the two directory paths does not match.
+        Error if the ``data_source`` of the two directory paths does not match.
     """
     raw_data_source = infer_data_source_from_path(raw_dir)
     processed_data_source = infer_data_source_from_path(processed_dir)
@@ -88,7 +88,7 @@ def _check_data_source_consistency(raw_dir: str, processed_dir: str) -> str:
 
 
 def _check_campaign_name_consistency(raw_dir: str, processed_dir: str) -> str:
-    """Check that 'raw_dir' and 'processed_dir' have same campaign_name.
+    """Check that ``raw_dir`` and ``processed_dir`` have same campaign_name.
 
     Parameters
     ----------
@@ -100,12 +100,12 @@ def _check_campaign_name_consistency(raw_dir: str, processed_dir: str) -> str:
     Returns
     -------
     str
-        Campaign name in capital letter.
+        ``campaign_name`` in capital letter.
 
     Raises
     ------
     ValueError
-        Error if the campaign_name of the two directory paths does not match.
+        Error if the ``campaign_name`` of the two directory paths does not match.
     """
     raw_campaign_name = infer_campaign_name_from_path(raw_dir)
     processed_campaign_name = infer_campaign_name_from_path(processed_dir)
@@ -119,7 +119,7 @@ def _check_campaign_name_consistency(raw_dir: str, processed_dir: str) -> str:
 def _copy_station_metadata(
     data_source: str, campaign_name: str, station_name: str, base_dir: str = None, check_validity: bool = False
 ) -> None:
-    """Copy the station YAML file from the raw_dir/metadata into processed_dir/metadata
+    """Copy the station YAML file from the ``raw_dir/metadata`` into ``processed_dir/metadata``.
 
     Parameters
     ----------
@@ -163,12 +163,12 @@ def _check_pre_existing_station_data(
 ):
     """Check for pre-existing station data.
 
-    - If force=True, remove all data inside the station directory.
-    - If force=False, raise error.
-
-    NOTE: force=False behaviour could be changed to enable updating of missing files.
-         This would require also adding code to check whether a downstream file already exist.
+    - If ``force=True``, remove all data inside the station directory.
+    - If ``force=False``, raise error.
     """
+    # NOTE: ``force=False`` behaviour could be changed to enable updating of missing files.
+    # This would require also adding code to check whether a downstream file already exist.
+
     # Check if there are available data
     available_data = has_available_station_files(
         product=product,
@@ -211,8 +211,11 @@ def create_l0_directory_structure(
 ):
     """Create directory structure for the first L0 DISDRODB product.
 
-    If the input data are raw text files --> product = "L0A"    (run_l0a)
-    If the input data are raw netCDF files --> product = "L0B"  (run_l0b_nc)
+    If the input data are raw text files, use ``product = "L0A"``
+    If the input data are raw netCDF files, use ``product = "L0B"``
+
+    ``product = "L0A"`` will call ``run_l0a``.
+    ``product = "L0B"`` will call ``run_l0b_nc``.
     """
     # Check inputs
     raw_dir = check_raw_dir(raw_dir=raw_dir, station_name=station_name)
@@ -315,7 +318,7 @@ def _create_station_directories(
     product="RAW",
     base_dir=None,
 ):
-    """Create the /metadata, /issue and /data/<station_name> directories of a station."""
+    """Create the ``/metadata``, ``/issue`` and ``/data/<station_name>`` directories of a station."""
     # Create directory structure
     _ = create_station_directory(
         base_dir=base_dir,