Skip to content

Commit

Permalink
chore: add html documentation page to the toolbox with sphinx (#118)
Browse files Browse the repository at this point in the history
first commit with some html documentation of the toolbox
  • Loading branch information
renaudjester committed Oct 28, 2024
1 parent 9044cf4 commit 8347832
Show file tree
Hide file tree
Showing 76 changed files with 8,252 additions and 229 deletions.
6 changes: 6 additions & 0 deletions conda_environment_sphinx.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
dependencies:
- python==3.9.18
- pip
- pip:
- shinx==7.4.7
- sphinx-click==6.0.0
4 changes: 0 additions & 4 deletions copernicusmarine/__init__.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
"""
.
"""

import logging.config
import time
from importlib.metadata import version
Expand Down
6 changes: 3 additions & 3 deletions copernicusmarine/catalogue_parser/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ class WebApi(Enum):


class ServiceNotHandled(Exception):
...
pass


# service formats
Expand Down Expand Up @@ -507,11 +507,11 @@ def filter_only_official_versions_and_parts(self):

# Errors
class DatasetVersionPartNotFound(Exception):
...
pass


class DatasetVersionNotFound(Exception):
...
pass


def dataset_version_part_not_found_exception(
Expand Down
3 changes: 0 additions & 3 deletions copernicusmarine/command_line_interface/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +0,0 @@
"""
.
"""
20 changes: 8 additions & 12 deletions copernicusmarine/command_line_interface/copernicus_marine.py
Original file line number Diff line number Diff line change
@@ -1,22 +1,18 @@
import click

from copernicusmarine.command_line_interface.group_describe import (
cli_group_describe,
)
from copernicusmarine.command_line_interface.group_get import cli_group_get
from copernicusmarine.command_line_interface.group_login import cli_group_login
from copernicusmarine.command_line_interface.group_subset import (
cli_group_subset,
)
from copernicusmarine.command_line_interface.group_describe import cli_describe
from copernicusmarine.command_line_interface.group_get import cli_get
from copernicusmarine.command_line_interface.group_login import cli_login
from copernicusmarine.command_line_interface.group_subset import cli_subset


@click.command(
cls=click.CommandCollection,
sources=[
cli_group_describe,
cli_group_login,
cli_group_subset,
cli_group_get,
cli_describe,
cli_login,
cli_subset,
cli_get,
],
context_settings=dict(help_option_names=["-h", "--help"]),
)
Expand Down
24 changes: 10 additions & 14 deletions copernicusmarine/command_line_interface/group_describe.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,33 +17,29 @@


@click.group()
def cli_group_describe() -> None:
def cli_describe() -> None:
pass


@cli_group_describe.command(
@cli_describe.command(
"describe",
cls=DeprecatedClickOptionsCommand,
short_help="Print Copernicus Marine catalog as JSON.",
help="""
Print Copernicus Marine catalog as JSON.
The default display contains information on the products, and more data
can be displayed using the --include-<argument> flags.
The default display contains information on the products, and more data can be displayed using the ``--include-<argument>`` flags.
The --contains option allows the user to specify one or several strings to
filter through the catalogue display. The search is performed recursively
on all attributes of the catalogue, and the tokens only need to be
contained in one of the attributes (i.e. not exact match).
""",
The ``--contains`` option allows the user to specify one or several strings to filter through the catalog display. The search is performed recursively on all attributes of the catalog, and the tokens only need to be contained in one of the attributes (i.e., not an exact match).
""", # noqa
epilog="""
Examples:
.. code-block:: bash
copernicusmarine describe --contains METOFFICE-GLO-SST-L4-NRT-OBS-SST-V2 --include-datasets
\b
copernicusmarine describe --contains METOFFICE-GLO-SST-L4-NRT-OBS-SST-V2 --include-datasets
.. code-block:: bash
\b
copernicusmarine describe -c METOFFICE-GLO-SST-L4-NRT-OBS-SST-V2
copernicusmarine describe -c METOFFICE-GLO-SST-L4-NRT-OBS-SST-V2
""", # noqa
)
@click.option(
Expand Down
14 changes: 6 additions & 8 deletions copernicusmarine/command_line_interface/group_get.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,26 +33,24 @@


@click.group()
def cli_group_get() -> None:
def cli_get() -> None:
pass


@cli_group_get.command(
@cli_get.command(
"get",
cls=DeprecatedClickOptionsCommand,
short_help="Download originally produced data files.",
help="""
Download originally produced data files.
--dataset-id is required (can be found via the "describe" command).
The function fetches the files recursively if a folder path is passed as URL.
When provided a datasetID, all the files in the corresponding folder will be downloaded if none of the --filter or --regex options is specified.
The ``--dataset-id`` is required (can be found via the "describe" command). The function fetches the files recursively if a folder path is passed as a URL. When provided a dataset ID, all the files in the corresponding folder will be downloaded if none of the ``--filter`` or ``--regex`` options is specified.
""", # noqa
epilog="""
Examples:
.. code-block:: bash
\b
copernicusmarine get -nd -o data_folder --dataset-id cmems_mod_nws_bgc-pft_myint_7km-3D-diato_P1M-m
# Example: Download all files from a dataset
copernicusmarine get -i cmems_mod_nws_bgc-pft_myint_7km-3D-diato_P1M-m
""", # noqa
)
@click.option(
Expand Down
25 changes: 13 additions & 12 deletions copernicusmarine/command_line_interface/group_login.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,31 +16,32 @@


@click.group()
def cli_group_login() -> None:
def cli_login() -> None:
pass


@cli_group_login.command(
@cli_login.command(
"login",
short_help="Create a configuration file with your Copernicus Marine credentials.",
help="""
Create a configuration file with your Copernicus Marine credentials.
Create a configuration file under the $HOME/.copernicusmarine directory (overwritable with option --credentials-file).
Create a configuration file under the ``$HOME/.copernicusmarine`` directory (overwritable with the ``--credentials-file`` option).
""", # noqa
epilog="""
Examples:
.. code-block:: bash
\b
COPERNICUSMARINE_SERVICE_USERNAME=<USERNAME> COPERNICUSMARINE_SERVICE_PASSWORD=<PASSWORD> copernicusmarine login
COPERNICUSMARINE_SERVICE_USERNAME=<USERNAME> COPERNICUSMARINE_SERVICE_PASSWORD=<PASSWORD> copernicusmarine login
\b
copernicusmarine login --username <USERNAME> --password <PASSWORD>
.. code-block:: bash
\b
copernicusmarine login
> Username: [USER-INPUT]
> Password: [USER-INPUT]
copernicusmarine login --username <USERNAME> --password <PASSWORD>
.. code-block:: bash
copernicusmarine login
> Username: [USER-INPUT]
> Password: [USER-INPUT]
""", # noqa
)
@click.option(
Expand Down
36 changes: 20 additions & 16 deletions copernicusmarine/command_line_interface/group_subset.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,35 +42,39 @@


@click.group()
def cli_group_subset() -> None:
def cli_subset() -> None:
pass


@cli_group_subset.command(
@cli_subset.command(
"subset",
cls=DeprecatedClickOptionsCommand,
short_help="Download subsets of datasets as NetCDF files or Zarr stores.",
help="""
Download subsets of datasets as NetCDF files or Zarr stores.
--dataset-id is required (can be found via the "describe" command).
The argument values passed individually through the CLI take precedence over the values from the --motu-api-request option,
which takes precedence over the ones from the --request-file option.
The ``--dataset-id`` is required (can be found via the "describe" command). The argument values passed individually through the CLI take precedence over the values from the ``--motu-api-request`` option, which takes precedence over the ones from the ``--request-file`` option.
""", # noqa
epilog="""
Examples:
.. code-block:: bash
\b
copernicusmarine subset
--dataset-id cmems_mod_glo_phy-thetao_anfc_0.083deg_PT6H-i
--variable thetao
--start-datetime 2022-01-01T00:00:00 --end-datetime 2022-12-31T23:59:59
--minimum-longitude -6.17 --maximum-longitude -5.08
--minimum-latitude 35.75 --maximum-latitude 36.30
--minimum-depth 0.0 --maximum-depth 5.0
copernicusmarine subset
--dataset-id cmems_mod_glo_phy-thetao_anfc_0.083deg_PT6H-i
--variable thetao
--start-datetime 2022-01-01T00:00:00
--end-datetime 2022-12-31T23:59:59
--minimum-longitude -6.17
--maximum-longitude -5.08
--minimum-latitude 35.75
--maximum-latitude 36.30
--minimum-depth 0.0
--maximum-depth 5.0
\b
copernicusmarine subset -i cmems_mod_glo_phy-thetao_anfc_0.083deg_PT6H-i -v thetao -t 2022-01-01T00:00:00 -T 2022-12-31T23:59:59 -x -6.17 -X -5.08 -y 35.75 -Y 36.30 -z 0.0 -Z 5.0
Equivalent to:
.. code-block:: bash
copernicusmarine subset -i cmems_mod_glo_phy-thetao_anfc_0.083deg_PT6H-i -v thetao -t 2022-01-01T00:00:00 -T 2022-12-31T23:59:59 -x -6.17 -X -5.08 -y 35.75 -Y 36.30 -z 0.0 -Z 5.0
""", # noqa
)
@click.option(
Expand Down
2 changes: 1 addition & 1 deletion copernicusmarine/command_line_interface/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ def handle_parse_result(self, ctx, opts, args):


class OtherOptionsPassedWithCreateTemplate(Exception):
...
pass


def assert_cli_args_are_not_set_except_create_template(
Expand Down
4 changes: 2 additions & 2 deletions copernicusmarine/core_functions/credentials_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,11 @@


class CredentialCannotBeNone(Exception):
...
pass


class InvalidUsernameOrPassword(Exception):
...
pass


def _load_credential_from_copernicus_marine_configuration_file(
Expand Down
4 changes: 2 additions & 2 deletions copernicusmarine/core_functions/services_utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -444,7 +444,7 @@ def _get_dataset_start_date_from_service(


class ServiceNotAvailable(Exception):
...
pass


def _warning_dataset_will_be_deprecated(
Expand Down Expand Up @@ -498,7 +498,7 @@ def _service_not_available_error(


class NoServiceAvailable(Exception):
...
pass


def _no_service_available_for_command(
Expand Down
2 changes: 1 addition & 1 deletion copernicusmarine/core_functions/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ def construct_query_params_for_marine_data_store_monitoring(


class WrongDatetimeFormat(Exception):
...
pass


def datetime_parser(string: str) -> datetime:
Expand Down
25 changes: 15 additions & 10 deletions copernicusmarine/python_interface/describe.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,21 @@ def describe(
This function fetches metadata information from the Copernicus Marine catalogue
based on specified parameters and options.
Args:
include_description (bool, optional): Whether to include description for each product. Defaults to False.
include_datasets (bool, optional): Whether to include dataset information. Defaults to False.
include_keywords (bool, optional): Whether to include keywords for each product. Defaults to False.
include_versions (bool, optional): Whether to include all versions of each dataset. Defaults to False.
include_all (bool, optional): Whether to include all metadata information. Defaults to False.
contains (list[str], optional): List of strings to filter items containing these values. Defaults to [].
Returns:
dict[str, Any]: A dictionary containing the retrieved metadata information.
:param include_description: Whether to include description for each product. Defaults to False.
:type include_description: bool, optional
:param include_datasets: Whether to include dataset information. Defaults to False.
:type include_datasets: bool, optional
:param include_keywords: Whether to include keywords for each product. Defaults to False.
:type include_keywords: bool, optional
:param include_versions: Whether to include all versions of each dataset. Defaults to False.
:type include_versions: bool, optional
:param include_all: Whether to include all metadata information. Defaults to False.
:type include_all: bool, optional
:param contains: List of strings to filter items containing these values. Defaults to [].
:type contains: list[str], optional
:returns: A dictionary containing the retrieved metadata information.
:rtype: dict[str, Any]
""" # noqa

if not isinstance(contains, list):
Expand Down
Loading

0 comments on commit 8347832

Please sign in to comment.