Merge pull request #951 from xcube-dev/forman-docstrings_from_rest_to…

…_google

Converted docstrings from reST to Google style

CHANGES.md

@@ -10,6 +10,11 @@
 
 * Renamed xcube's main branch from `master` to `main` on GitHub.
 
+* xcube's code base changed its docstring format from reST style to the much better 
+  readable [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+  Existing docstrings have been converted using the awesome [docconvert](https://github.com/cbillingham/docconvert) 
+  tool.
+
 
 ## Changes in 1.4.1
 

docs/source/conf.py

@@ -27,7 +27,7 @@
 
 
 project = 'xcube'
-copyright = '2023, Brockmann Consult GmbH'
+copyright = '2018-2024, Brockmann Consult GmbH'
 author = 'Brockmann Consult GmbH'
 
 # The full version, including alpha/beta/rc tags
@@ -59,6 +59,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
     'sphinx_autodoc_annotation',
     'sphinxarg.ext',
     'recommonmark',

docs/source/cubespec.md

@@ -219,7 +219,7 @@ which is also the default name used by the Zarr format.
 The format of the consolidated metadata must be JSON. It is a 
 JSON object using the following structure:
 
-```json
+```
     {
         "zarr_consolidated_format": 1,
         "metadata": {

docs/source/devguide.md

@@ -179,7 +179,8 @@ Make sure your change
 
 Create new module in `xcube.core` and add your functions.
 For any functions added make sure naming is in line with other API.
-Add clear doc-string to the new API. Use Sphinx RST format.
+Add clear doc-string to the new API using 
+[Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
 
 Decide if your API methods requires [xcube datasets](./cubespec.md) as 
 inputs, if so, name the primary dataset argument `cube` and add a 

docs/source/examples/xcube_gen.rst

@@ -27,7 +27,7 @@ Before starting the example, you need to activate the xcube environment:
 
     $ conda activate xcube
 
-If you want to take a look at the input data you can use :doc:`cli/xcube dump` to print out the metadata of a selected input file:
+If you want to take a look at the input data you can use :doc:`../cli/xcube_dump` to print out the metadata of a selected input file:
 
 ::
 
@@ -153,7 +153,7 @@ Optimizing and pruning a xcube dataset
 ======================================
 
 If you want to optimize your generated xcube dataset e.g. for publishing it in a xcube viewer via xcube serve
-you can use  :doc:`cli/xcube optimize`:
+you can use  :doc:`../cli/xcube_optimize`:
 
 ::
 
@@ -165,7 +165,7 @@ a file called .zmetadata. .zmetadata contains the information stored in .zattrs
 xcube dataset and makes requests of metadata faster. The option ``-C`` optimizes coordinate variables by converting any
 chunked arrays into single, non-chunked, contiguous arrays.
 
-For deleting empty chunks :doc:`cli/xcube prune` can be used. It deletes all data files associated with empty (NaN-only)
+For deleting empty chunks :doc:`../cli/xcube_prune` can be used. It deletes all data files associated with empty (NaN-only)
 chunks of an xcube dataset, and is restricted to the ZARR format.
 
 ::
@@ -175,7 +175,7 @@ chunks of an xcube dataset, and is restricted to the ZARR format.
 The pruned xcube dataset is saved in place and does not need an output path. The size of the xcube dataset was 6,8 MB before pruning it
 and 6,5 MB afterwards. According to the output printed to the terminal, 30 block files were deleted.
 
-The metadata of the xcube dataset can be viewed with :doc:`cli/xcube dump` as well:
+The metadata of the xcube dataset can be viewed with :doc:`../cli/xcube_dump` as well:
 
 ::
 

xcube/cli/common.py

@@ -41,9 +41,7 @@ def _callback(ctx: click.Context, param: click.Option, value: bool):
 
 
 def cli_option_quiet(func):
-    """
-    Decorator for adding a reusable CLI option `--quiet`/'-q'.
-    """
+    """Decorator for adding a reusable CLI option `--quiet`/'-q'."""
 
     # noinspection PyUnusedLocal
     def _callback(ctx: click.Context, param: click.Option, value: bool):
@@ -62,8 +60,7 @@ def _callback(ctx: click.Context, param: click.Option, value: bool):
 
 
 def cli_option_verbosity(func):
-    """
-    Decorator for adding a reusable CLI option `--verbose`/'-v' that
+    """Decorator for adding a reusable CLI option `--verbose`/'-v' that
     can be used multiple times.
     The related kwarg is named `verbosity` and is of type int (= count).
     """
@@ -92,8 +89,7 @@ def _callback(ctx: click.Context, param: click.Option, value: int):
 
 
 def cli_option_dry_run(func):
-    """
-    Decorator for adding a reusable CLI option `--dry-run`/'-d'.
+    """Decorator for adding a reusable CLI option `--dry-run`/'-d'.
     The related kwarg is named `dry_run` and is of type bool.
     """
 
@@ -157,13 +153,15 @@ def _callback(ctx: click.Context, param: click.Option, value: Optional[str]):
 
 
 def parse_cli_kwargs(value: str, metavar: str = None) -> Dict[str, Any]:
-    """
-    Parse a string value of the form [<kw>=<arg>{,<kw>=<arg>}] into a dictionary.
+    """Parse a string value of the form [<kw>=<arg>{,<kw>=<arg>}] into a dictionary.
     <kw> must be a valid Python identifier, <arg> must be a Python literal.
 
-    :param value: A string value.
-    :param metavar: Name of a meta-variable used in CLI.
-    :return: a dictionary of keyword-arguments
+    Args:
+        value: A string value.
+        metavar: Name of a meta-variable used in CLI.
+
+    Returns:
+        a dictionary of keyword-arguments
     """
     if value:
         try:
@@ -193,23 +191,30 @@ def parse_cli_sequence(
     separator: str = ",",
     error_type: Type[Exception] = click.ClickException,
 ) -> Optional[Tuple[Any, ...]]:
-    """
-    Parse a CLI argument that is supposed to be a sequence.
-
-    :param seq_value: A string, a string sequence, or None.
-    :param metavar: CLI metavar name
-    :param item_parser: an optional function that takes a string and parses it
-    :param item_validator: a optional function that takes a parsed value and parses it
-    :param allow_none: whether it is ok for *seq_value* to be None
-    :param allow_empty_items: whether it is ok to have empty values in *seq_value*
-    :param strip_items: whether to strip values in *seq_value*
-    :param item_plural_name: a name for multiple items
-    :param num_items: expected number of items
-    :param num_items_min: expected minimum number of items
-    :param num_items_max: expected maximum number of items
-    :param separator: expected separator if *seq_value* is a string, default is ','.
-    :param error_type: value error to be raised in case, defaults to ``click.ClickException``
-    :return: parsed and validated *seq_value* as a tuple of values
+    """Parse a CLI argument that is supposed to be a sequence.
+
+    Args:
+        seq_value: A string, a string sequence, or None.
+        metavar: CLI metavar name
+        item_parser: an optional function that takes a string and parses
+            it
+        item_validator: a optional function that takes a parsed value
+            and parses it
+        allow_none: whether it is ok for *seq_value* to be None
+        allow_empty_items: whether it is ok to have empty values in
+            *seq_value*
+        strip_items: whether to strip values in *seq_value*
+        item_plural_name: a name for multiple items
+        num_items: expected number of items
+        num_items_min: expected minimum number of items
+        num_items_max: expected maximum number of items
+        separator: expected separator if *seq_value* is a string,
+            default is ','.
+        error_type: value error to be raised in case, defaults to
+            ``click.ClickException``
+
+    Returns:
+        parsed and validated *seq_value* as a tuple of values
     """
     if seq_value is None:
         if allow_none:
@@ -258,8 +263,7 @@ def parse_cli_sequence(
 
 
 def assert_positive_int_item(item: int):
-    """
-    A validator for positive integer number sequences.
+    """A validator for positive integer number sequences.
     Frequently used to validate counts or image and tile sizes passes as args to the CLI.
     """
     if item <= 0:

xcube/cli/compute.py

@@ -91,8 +91,7 @@ def compute(
     output_var_name: str,
     output_var_dtype: str,
 ):
-    """
-    Compute a cube from one or more other cubes.
+    """Compute a cube from one or more other cubes.
 
     The command computes a cube variable from other cube variables in CUBEs
     using a user-provided Python function in SCRIPT.

xcube/cli/dump.py

@@ -40,9 +40,7 @@
     help="Dump also variable encoding information.",
 )
 def dump(input, variable, encoding):
-    """
-    Dump contents of an input dataset.
-    """
+    """Dump contents of an input dataset."""
     from xcube.core.dsio import open_dataset
     from xcube.core.dump import dump_dataset
 

xcube/cli/extract.py

@@ -46,8 +46,7 @@ def extract(
     indexes=False,
     refs=False,
 ):
-    """
-    Extract cube points.
+    """Extract cube points.
 
     Extracts data cells from CUBE at coordinates given in each POINTS record and writes the resulting values to given
     output path and format.

xcube/cli/gen2.py

@@ -78,8 +78,7 @@ def gen2(
     quiet: bool = False,
     verbosity: int = 0,
 ):
-    """
-    Generator tool for data cubes.
+    """Generator tool for data cubes.
 
     Creates a cube view from one or more cube stores, optionally performs some
     cube transformation, and writes the resulting cube to some target cube

xcube/cli/genpts.py

@@ -43,8 +43,7 @@
     default=DEFAULT_NUM_POINTS_MAX,
 )
 def genpts(cube: str, output_path: str, num_points_max: int):
-    """
-    Generate synthetic data points from CUBE.
+    """Generate synthetic data points from CUBE.
 
     Generates synthetic data points for a given data CUBE and write points to a CSV and GeoJSON file.
     The primary use of the tool is to point datasets for machine learning tasks

xcube/cli/grid.py

@@ -262,8 +262,7 @@ def list_resolutions(
     num_results: int,
     sep: str,
 ):
-    """
-    List resolutions close to a target resolution.
+    """List resolutions close to a target resolution.
 
     Lists possible resolutions of a fixed Earth grid that are close to a given target
     resolution TARGET_RES within a maximum allowed deviation DELTA_RES.
@@ -343,8 +342,7 @@ def list_resolutions(
 def list_levels(
     res: str, height: int, coverage: str, level_min: Optional[int], sep: str
 ):
-    """
-    List levels for a resolution or a tile size.
+    """List levels for a resolution or a tile size.
 
     Lists the given number of LEVELS for given resolution RES or given height in grid cells HEIGHT.
     which can both be used to define a fixed Earth grid.
@@ -396,8 +394,7 @@ def adjust_box(
     coverage: str,
     tile_factor: Optional[int],
 ):
-    """
-    Adjust a bounding box to a fixed Earth grid.
+    """Adjust a bounding box to a fixed Earth grid.
 
     Adjusts a bounding box given by GEOM  to a fixed Earth grid by the
     inverse resolution INV_RES in degrees^-1 units, which must be an integer number.
@@ -495,8 +492,7 @@ def _fetch_coverage_from_option(coverage_str: str) -> fractions.Fraction:
 
 @click.group()
 def grid():
-    """
-    Find spatial xcube dataset resolutions and adjust bounding boxes.
+    """Find spatial xcube dataset resolutions and adjust bounding boxes.
 
     We find suitable resolutions with respect to a possibly regional fixed Earth grid and adjust regional spatial
     bounding boxes to that grid. We also try to select the resolutions such

xcube/cli/io.py

@@ -94,8 +94,7 @@ def store_info(
     show_data_ids: bool,
     use_json_format: bool,
 ):
-    """
-    Show data store information.
+    """Show data store information.
 
     Dumps detailed data store information in human readable form or as JSON, when using the --json option.
 
@@ -167,8 +166,7 @@ def store_info(
 @click.argument("data_id", metavar="DATA")
 @click.argument("store_params", metavar="PARAMS", nargs=-1)
 def store_data(store_id: str, data_id: str, store_params: List[str]):
-    """
-    Show data resource information.
+    """Show data resource information.
 
     Show the data descriptor for data resource DATA in data store STORE.
     Note some stores require provision of store parameters PARAMS.
@@ -183,8 +181,7 @@ def store_data(store_id: str, data_id: str, store_params: List[str]):
 @click.command(name="info")
 @click.argument("opener_id", metavar="OPENER")
 def opener_info(opener_id: str):
-    """
-    Show data opener information.
+    """Show data opener information.
     You can obtain valid OPENER names using command "xcube io opener list".
     """
     extension = get_extension_registry().get_extension(
@@ -203,8 +200,7 @@ def opener_info(opener_id: str):
 @click.command(name="info")
 @click.argument("writer_id", metavar="WRITER")
 def writer_info(writer_id: str):
-    """
-    Show data opener information.
+    """Show data opener information.
     You can obtain valid WRITER names using command "xcube io writer list".
     """
     extension = get_extension_registry().get_extension(
@@ -305,8 +301,7 @@ def dump(
     yaml_format: bool,
     json_format: bool,
 ):
-    """
-    Dump metadata of given data stores.
+    """Dump metadata of given data stores.
 
     Dumps data store metadata and metadata for a store's data resources
     for given data stores  into a JSON file.
@@ -562,25 +557,19 @@ def _parse_props(props: str) -> Dict[str, AbstractSet]:
 
 @click.group()
 def store():
-    """
-    Tools for xcube's data stores.
-    """
+    """Tools for xcube's data stores."""
     pass
 
 
 @click.group()
 def opener():
-    """
-    Tools for xcube's data openers.
-    """
+    """Tools for xcube's data openers."""
     pass
 
 
 @click.group()
 def writer():
-    """
-    Tools for xcube's data writers.
-    """
+    """Tools for xcube's data writers."""
     pass
 
 
@@ -595,9 +584,7 @@ def writer():
 
 @click.group(hidden=True)
 def io():
-    """
-    Tools for xcube's generic I/O system.
-    """
+    """Tools for xcube's generic I/O system."""
     pass
 
 

xcube/cli/level.py

@@ -117,8 +117,7 @@ def level(
     quiet: bool,
     verbosity: int,
 ):
-    """
-    Generate multi-resolution levels.
+    """Generate multi-resolution levels.
 
     Transform the given dataset by INPUT into the levels of a
     multi-level pyramid with spatial resolution decreasing by a

xcube/cli/main.py

@@ -75,9 +75,7 @@
     " (warnings are hidden by default).",
 )
 def cli(traceback=False, scheduler=None, log_level=None, log_file=None, warnings=None):
-    """
-    xcube Toolkit
-    """
+    """xcube Toolkit"""
     configure_logging(log_file=log_file, log_level=log_level)
     configure_warnings(warnings)