diff --git a/.gitignore b/.gitignore index ab7a127..c7dfb9a 100644 --- a/.gitignore +++ b/.gitignore @@ -73,6 +73,9 @@ docs/doctrees/ docs/html/ docs/build/ +# mkdocs +site/ + # External Sources #src/external src/ diff --git a/CHANGELOG.rst b/CHANGELOG.rst deleted file mode 100644 index 4182c5b..0000000 --- a/CHANGELOG.rst +++ /dev/null @@ -1,69 +0,0 @@ -Release Notes -************* - -Unreleased -~~~~~~~~~~ -* Change CDS keys from .cdsapirc file to .config/eracli.txt file. This will avoid conflict with e.g. ADS. -* Add validator for era5cli.txt keys. This should provide better feedback to users and reduce user error. -* Added --splitmonths argument for `era5cli hourly`. This allows users to avoid a Request Too Large error. -* If a user makes a request without --splitmonths they are warned that the behavior will change in the future, and that they have to choose between --splitmonths False and --splitmonths True. -* When a request would encounter a Request Too Large error in the CDS API, they are warned, and given a suggestion to use --splitmonths. -* cli.py has been refactored to make the structure more clear. Seperate argument builders are now in their own modules. - -1.3.2 (2021-12-13) -~~~~~~~~~~~~~~~~~~ -* Elaborate the range of years that can be queried `#123 `_ -* Update Readthedocs theme `#125 `_ -* Fix a bug that allowed the incompatible combination of --land and --ensemble `#131 `_ - -1.3.1 (2021-12-01) -~~~~~~~~~~~~~~~~~~ -* Automatic Zenodo/RSD release failed; updated contribution guidelines `#106 `_ - -1.3.0 (2021-11-30) -~~~~~~~~~~~~~~~~~~ -* Fix compatibility with changed CDS variables geopotential/orography `#98 `_ -* Add integration testing `#102 `_ - -1.2.1 (2021-04-21) -~~~~~~~~~~~~~~~~~~ -* Automatic PyPI release for 1.2.0 failed; updated github action workflow `#91 `_ - -1.2.0 (2021-04-21) -~~~~~~~~~~~~~~~~~~ -* Add support for ERA5-Land data `#67 `_ -* Add functionality to download subregions `#70 `_ -* Update variables available for ERA5 datasets `#84 `_ - -1.1.1 (2020-12-15) -~~~~~~~~~~~~~~~~~~ -* Patch to fix the github actions publish automation `#64 `_ - -1.1.0 (2020-12-14) -~~~~~~~~~~~~~~~~~~ -* The stable 1.1.0 era5cli minor release. -* Add support for ERA5 preliminary back extension `#58 `_ -* Update tests `#57 `_ -* Add automated PyPI package building and publishing with github Actions `#62 `_ - -1.0.0 (2019-07-25) -~~~~~~~~~~~~~~~~~~ -* The stable 1.0.0 era5cli release. -* Adding more useful information to netCDF history `#48 `_ - -1.0.0rc3 (2019-07-16) -~~~~~~~~~~~~~~~~~~~~~ -* Third Release Candidate for the stable 1.0.0 era5cli release. -* Improve documentation `#21 `_ `#29 `_. -* Cleanup command line options `#19 `_ `#20 `_. -* Append era5cli version to history of downloaded netCDF file `#17 `_. - -1.0.0rc2 (2019-07-01) -~~~~~~~~~~~~~~~~~~~~~ -* Second Release Candidate for the stable 1.0.0 era5cli release. -* Fix downloading all variables when requesting multiple variables and using --split `#23 `_. -* Fix link to PyPI package in documentation `#22 `_. - -1.0.0rc1 (2019-06-22) -~~~~~~~~~~~~~~~~~~~~~ -* First Release Candidate for the stable 1.0.0 era5cli release: A commandline utility to download ERA-5 data using cdsapi. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d30e28 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +Logo + + +[![github license badge](https://img.shields.io/github/license/eWaterCycle/era5cli)](https://github.com/eWaterCycle/era5cli) +[![rsd badge](https://img.shields.io/badge/RSD-era5cli-blue)](https://research-software-directory.org/software/era5cli) +[![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3252665.svg)](https://doi.org/10.5281/zenodo.3252665) + +[![Documentation Status](https://readthedocs.org/projects/era5cli/badge/?version=stable)](https://lilio.readthedocs.io/en/stable/?badge=stable) +[![build](https://github.com/eWaterCycle/era5cli/actions/workflows/test_and_build.yml/badge.svg)](https://github.com/eWaterCycle/era5cli/actions/workflows/test_and_build.yml) +[![Test Coverage](https://codecov.io/gh/eWaterCycle/era5cli/branch/main/graph/badge.svg?token=qeZXgGASBK)](https://codecov.io/gh/eWaterCycle/era5cli) +[![PyPI](https://badge.fury.io/py/era5cli.svg)](https://badge.fury.io/py/era5cli) + + +A command line interface to download ERA5 data from the [Copernicus Climate Data Store](). + +
+ +With `era5cli` you can: + + - Download meteorological data in GRIB/NetCDF, including ERA5 data from the preliminary back extension, and ERA5-Land data. + - List and retrieve information on available variables and pressure levels + - Select multiple variables for several months and years + - Split outputs by years (and optionally months), producing a separate files instead of merging them in one file + - Download multiple files at once + - Extract data for a sub-region of the globe + +
+ +Free software: Apache Software License 2.0 + +Documentation: https://era5cli.readthedocs.io + diff --git a/README.rst b/README.rst deleted file mode 100644 index bcc039e..0000000 --- a/README.rst +++ /dev/null @@ -1,48 +0,0 @@ -era5cli -======= -.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 - :alt: License - -.. image:: https://readthedocs.org/projects/era5cli/badge/?version=stable - :target: https://era5cli.readthedocs.io/en/stable/?badge=stable - :alt: Documentation Status - -.. image:: https://github.com/eWaterCycle/era5cli/actions/workflows/test_codecov.yml/badge.svg - :target: https://github.com/eWaterCycle/era5cli/actions/workflows/test_codecov.yml - :alt: Github Actions - -.. image:: https://codecov.io/gh/eWaterCycle/era5cli/branch/main/graph/badge.svg?token=qeZXgGASBK - :target: https://codecov.io/gh/eWaterCycle/era5cli - :alt: Test coverage - -.. image:: https://badge.fury.io/py/era5cli.svg - :target: https://badge.fury.io/py/era5cli - -.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3252665.svg - :target: https://doi.org/10.5281/zenodo.3252665 - -.. image:: https://img.shields.io/badge/rsd-era5cli-00a3e3.svg - :target: https://www.research-software.nl/software/era5cli - :alt: Research Software Directory Badge - -.. image:: https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow - :target: https://fair-software.eu - -.. inclusion-marker-start-do-not-remove - -A command line interface to download ERA5 data from the `Copernicus Climate Data Store `_. - -With era5cli you can: - -- download meteorological data in GRIB/NetCDF, including ERA5 data from the preliminary back extension, and ERA5-Land data. -- list and retrieve information on available variables and pressure levels -- select multiple variables for several months and years -- split outputs by years, producing a separate file for every year instead of merging them in one file -- download multiple files at once -- extract data for a sub-region of the globe - -.. inclusion-marker-end-do-not-remove - -| Free software: Apache Software License 2.0 -| Documentation: https://era5cli.readthedocs.io diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..2653c60 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,107 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased +**Added:** + + - Add validator for `era5cli.txt` keys. This should provide better feedback to users and reduce user error. + - Added --splitmonths argument for `era5cli hourly`. This allows users to avoid a Request Too Large error. + +**Changed:** + + - Change CDS keys from `.cdsapirc` file to `.config/eracli.txt` file. This will avoid conflict with e.g. ADS. + - If a user makes a request without `--splitmonths` they are warned that the behavior will change in the future, and that they have to choose between `--splitmonths False` and `--splitmonths True`. + - When a request would encounter a Request Too Large error in the CDS API, they are warned, and given a suggestion to use `--splitmonths`. + - `cli.py` has been refactored to make the structure more clear. Seperate argument builders are now in their own modules. + - The documentation has been overhauled, and now uses Markdown files & MkDocs. + +## 1.3.2 - 2021-12-13 +**Changed:** + + - Elaborate the range of years that can be queried [#123](https://github.com/eWaterCycle/era5cli/pull/123) + - Update Readthedocs theme [#125](https://github.com/eWaterCycle/era5cli/pull/125) + +**Fixed:** + + - Fix a bug that allowed the incompatible combination of --land and --ensemble [#131](https://github.com/eWaterCycle/era5cli/pull/131) + + +## 1.3.1 - 2021-12-01 +**Fixed:** + + - Automatic Zenodo/RSD release failed; updated contribution guidelines [#106](https://github.com/eWaterCycle/era5cli/pull/106) + +## 1.3.0 - 2021-11-30 +**Added:** + + - Add integration testing [#102](https://github.com/eWaterCycle/era5cli/pull/102) + +**Fixed:** + + - Fix compatibility with changed CDS variables geopotential/orography [#98](https://github.com/eWaterCycle/era5cli/pull/98) + +## 1.2.1 - 2021-04-21 +**Fixed:** + + - Automatic PyPI release for 1.2.0 failed; updated github action workflow [#91](https://github.com/eWaterCycle/era5cli/pull/91) + +## 1.2.0 - 2021-04-21 +**Added:** + + - Add support for ERA5-Land data [#67](https://github.com/eWaterCycle/era5cli/pull/67) + - Add functionality to download subregions [#70](https://github.com/eWaterCycle/era5cli/pull/70) + +**Changed:** + + - Update variables available for ERA5 datasets [#84](https://github.com/eWaterCycle/era5cli/pull/84) + +## 1.1.1 - 2020-12-15 +**Fixed:** + + - Patch to fix the github actions publish automation [#64](https://github.com/eWaterCycle/era5cli/pull/64) + +## 1.1.0 - 2020-12-14 +The stable 1.1.0 era5cli minor release. + +**Added:** + + - Add support for ERA5 preliminary back extension [#58](https://github.com/eWaterCycle/era5cli/pull/58) + - Add automated PyPI package building and publishing with github Actions [#62](https://github.com/eWaterCycle/era5cli/pull/62) + +**Changed:** + + - Update tests [#57](https://github.com/eWaterCycle/era5cli/pull/57) + +## 1.0.0 - 2019-07-25 +The stable 1.0.0 era5cli release. + +**Added:** + + - Adding more useful information to netCDF history [#48](https://github.com/eWaterCycle/era5cli/pull/48) + +## 1.0.0rc3 - 2019-07-16 +Third Release Candidate for the stable 1.0.0 era5cli release. + +**Added:** + + - Append era5cli version to history of downloaded netCDF file [#17](https://github.com/eWaterCycle/era5cli/issues/17) + +**Changed:** + + - Improve documentation [#21](https://github.com/eWaterCycle/era5cli/issues/21) [#29](https://github.com/eWaterCycle/era5cli/issues/29) + - Cleanup command line options [#19](https://github.com/eWaterCycle/era5cli/issues/19) [#20](https://github.com/eWaterCycle/era5cli/issues/20) + +## 1.0.0rc2 - 2019-07-01 +Second Release Candidate for the stable 1.0.0 era5cli release. + +**Fixed:** + + - Fix downloading all variables when requesting multiple variables and using --split [#23](https://github.com/eWaterCycle/era5cli/issues/23) + - Fix link to PyPI package in documentation [#22](https://github.com/eWaterCycle/era5cli/issues/22) + +## 1.0.0rc1 - 2019-06-22 +First Release Candidate for the stable 1.0.0 era5cli release: A commandline utility to download ERA-5 data using cdsapi. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/assets/era5cli_favicon.png b/docs/assets/era5cli_favicon.png new file mode 100644 index 0000000..2e6b4ed Binary files /dev/null and b/docs/assets/era5cli_favicon.png differ diff --git a/docs/assets/era5cli_logo_colors.png b/docs/assets/era5cli_logo_colors.png new file mode 100644 index 0000000..2c0f9ce Binary files /dev/null and b/docs/assets/era5cli_logo_colors.png differ diff --git a/docs/assets/era5cli_logo_colors_border.png b/docs/assets/era5cli_logo_colors_border.png new file mode 100644 index 0000000..bbb289e Binary files /dev/null and b/docs/assets/era5cli_logo_colors_border.png differ diff --git a/docs/source/contribute.rst b/docs/contribute.md similarity index 67% rename from docs/source/contribute.rst rename to docs/contribute.md index 575db35..3d2b380 100644 --- a/docs/source/contribute.rst +++ b/docs/contribute.md @@ -1,29 +1,27 @@ -Contribute -********** +# Contributing to era5cli -Bug reports -=========== +## Bug reports File bug reports or feature requests, and make contributions (e.g. code -patches), by `opening a new issue on GitHub `_. +patches), by [opening a new issue on GitHub](https://github.com/ewatercycle/era5cli/issues). Please give as much information as you can in the issue. It is very useful if you can supply the command or a small self-contained code snippet that reproduces the problem. Please also specify the era5cli version that you are using and the version of the cdsapi library installed. -Contribute to the tool -====================== +## Contribute to the tool Make sure `pip` and `hatch` are up to date: -:: - - python3 -m pip install pip hatch --upgrade +``` +python3 -m pip install pip hatch --upgrade +``` Create and activate the development environment: -:: - hatch shell # Or: python3 -m hatch shell +``` +hatch shell # Or: python3 -m hatch shell +``` This will start a virtual environment with the required dependencies to allow for development. Run this command before trying out any changes made to the code. @@ -32,25 +30,24 @@ Before pushing a new addition, some checks are required to confirm that the code is up to standard. To run the test suite: -:: - - hatch run test +``` +hatch run test +``` To format the code, and check the code styling: -:: - - hatch run format +``` +hatch run format +``` Exit the the environment with: -:: - - exit - +``` +exit +``` -Contribute to the documentation -=============================== +### Contribute to the documentation When updating the documentation, build the documentation with: -:: - hatch run docs:build +``` +hatch run docs:build +``` diff --git a/docs/dev.md b/docs/dev.md new file mode 100644 index 0000000..1333ed7 --- /dev/null +++ b/docs/dev.md @@ -0,0 +1 @@ +TODO diff --git a/docs/formulating_requests.md b/docs/formulating_requests.md new file mode 100644 index 0000000..ef49256 --- /dev/null +++ b/docs/formulating_requests.md @@ -0,0 +1,64 @@ +To be able to make a request, you need to decide on a few main points: + +- Which variables do you want? + - And in which dataset are these variables located? (E.g. ERA5-Land). +- For which years do you want the variable? +- Do you want to the data globally, or specify a bounding box (using `--area`). +- (*For pressure level data:*) on which levels do you want the data. + +!!! note + All available arguments are listed in the [CLI Reference](reference/arguments.md) + + +### Example request + +A typical request in `era5cli` can look like the following: + +``` +era5cli hourly \ + --land \ + --variables 2m_temperature 2m_dewpoint_temperature \ + --startyear 2000 \ + --endyear 2020 \ + --splitmonths True \ + --area 53.6 3.3 50.7 7.5 +``` + +This request asks for *hourly* data of the ERA5-*Land* dataset, more specifically the *2m_temperature* and *2m_dewpoint_temperature* variables. + +Additionally, data from the year *2000* up to (and including) *2020* is requested, with the final files being *split up by months*. +Lastly, an *area* is extracted from the dataset (in this case only the Netherlands). + +### Using the info command + +To be able to formulate a request, you can make use of the `--help` and `info` +arguments in era5cli. + +The `info` argument takes a name, out of the ones shown below. For example, + +``` +era5cli info levels +``` +will list all available pressure levels. + +| `info` argument | shows: | +|-----------------|-------| +| `levels` | available pressure levels | +| `2Dvars` | available single level / 2D variables | +| `3Dvars` | available pressure level / 3D variables | +| `land` | available variables in ERA5-land | + +???+ tip + You can enter a variable name (such as `total_precipitation`) to show if the variable is available, and in which list. + + For example: + ```sh + era5cli info total_precipitation + ``` + + returns: + ``` + total_precipitation is in the list(s): 2Dvars, land + ``` + +You can view the available variable names in the [CLI Reference](reference/variables.md) diff --git a/docs/gen_reference_pages.py b/docs/gen_reference_pages.py new file mode 100644 index 0000000..a01343e --- /dev/null +++ b/docs/gen_reference_pages.py @@ -0,0 +1,94 @@ +import mkdocs_gen_files +from era5cli import inputref +import era5cli.cli +import subprocess +from typing import List, Generator + + +def divide_chunks(biglist: List, n: int) -> Generator[List, None, None]: + """Divide a list in n-sized chunks""" + for i in range(0, len(biglist), n): + yield biglist[i : i + n] + + +def add_padding(multiline_string: List[str]): + """Add a 4-spaces padding to the start of every line.""" + multiline_string = multiline_string.replace("\n", "\n ") + return f" {multiline_string}" + + +# Build the variable reference markdown file from the input reference. +filename = "reference/variables.md" + +variable_data = [ # Full name, short name, inputreference, number of columns: + ("Available single level variables", "2D vars", inputref.PLVARS, 3), + ("Available pressure level variables", "3D vars", inputref.SLVARS, 2), + ( + "Available pressure levels", + "Pressure levels", + [str(p) for p in inputref.PLEVELS], + 4, + ), + ("Available ERA5-land variables", "ERA5-Land", inputref.ERA5_LAND_VARS, 2), +] + + +filename = "reference/variables.md" # Already exists, has the introductory text + + +with mkdocs_gen_files.open(filename, "a") as f: # Only append to file (!) + for full_name, short_name, ref, ncol in iter(variable_data): + print("", file=f) + print(f'=== "{short_name}"', file=f) + print("", file=f) + print(f" | {full_name} |{' |' * (ncol - 1)}", file=f) + print(f" |{'-|' * ncol}", file=f) + for chunk in divide_chunks(ref, ncol): + print(f" |{'|'.join(chunk)}|", file=f) + print("", file=f) + + +# Build the CLU usage reference docs: +filename = "reference/cli_usage.md" # Already exists, has the introductory text + + +with mkdocs_gen_files.open(filename, "a") as f: # Only append to file (!) + parser = era5cli.cli._build_parser() + parser_help = parser.format_help() + parser_help = parser_help.replace("`", "'") + parser_help = "\n".join(parser_help.split("\n")[2:]) + print("```", file=f) + print("$ era5cli --help", file=f) + print("", file=f) + print(parser_help, file=f) + print("```", file=f) + + +# Build the argument reference docs: +filename = "reference/arguments.md" # Already exists, has the introductory text + +with mkdocs_gen_files.open(filename, "a") as f: # Only append to file (!) + subparsers = ["Hourly", "Monthly"] + + for subp in subparsers: + with subprocess.Popen( + ["era5cli", subp.lower(), "--help"], stdout=subprocess.PIPE + ) as process: + stdout, stderr = process.communicate() + helpstr = stdout.decode("utf-8") + helpstr = helpstr[helpstr.index("optional arguments") :] + + # Split out \r\n (for Windows only?) + split_str = helpstr.splitlines() + helpstr = "\n".join(split_str) + + print("", file=f) + print(f'=== "{subp}"', file=f) + print("", file=f) + print(" ```", file=f) + print(f" $ era5cli {subp.lower()} --help", file=f) + print(" ", file=f) + print(add_padding(helpstr), file=f, end=None) + print(" ```", file=f) + +mkdocs_gen_files.set_edit_path(filename, "gen_reference_pages.py") diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..6d031e3 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,63 @@ + +## Installation + +For installation, multiple options are available depending on your setup: + +=== "pip" + + To install era5cli from PyPI, use the following command: + + ``` + pip install era5cli + ``` + +=== "conda" + + era5cli has been packaged for conda-forge. It can be installed from there with: + + ``` + conda install era5cli -c conda-forge + ``` + + +=== "development version" + + The development version is available via GitHub. To install directly from GitHub, the following command can be used: + + ``` + pip install -U git+https://github.com/eWaterCycle/era5cli.git + ``` + +***** + +| **Source** | PyPI (pip) | conda-forge | Github | +|------------|------------|-------------|--------| +| **Status** | [![](https://badge.fury.io/py/era5cli.svg)](https://pypi.org/project/era5cli/) | [![](https://anaconda.org/conda-forge/era5cli/badges/version.svg)](https://anaconda.org/conda-forge/era5cli) | [![](https://img.shields.io/github/commits-since/eWaterCycle/era5cli/latest.svg)](https://github.com/eWaterCycle/era5cli) | + +## Copernicus CDS credentials + +To be able to use era5cli, you need to be [**registered**](https://cds.climate.copernicus.eu/user/register?destination=%2F%23!%2Fhome) at the Copernicus Climate Data Service (CDS). + +After activating your account, **login** on the CDS website, go to your **profile page** (top right on the website), and view your **API keys** at the bottom of the page. + +To configure era5cli to use these keys, open up the environment you installed era5cli in, and do: + +```sh +era5cli config --uid ID_NUMBER --key "KEY" +``` + +*Where ID_NUMBER is your user ID (e.g. 123456) and "KEY" is your API key, inside double quotes (e.g. "4s215sgs-2dfa-6h34-62h2-1615ad163414").* + +After running this command your ID and key are validated and stored inside your home folder, under `.config/era5cli.txt.` + +## Your first request + +Now you should be able to make a request for data from the CDS. For example: + +```sh +era5cli monthly --variables soil_type --startyear 2000 --months 01 +``` + +Which will download the monthly mean `soil_type` data, for January 2000. + +*Note: this file is ~2 MB* diff --git a/docs/hourly_monthly.md b/docs/hourly_monthly.md new file mode 100644 index 0000000..10c083c --- /dev/null +++ b/docs/hourly_monthly.md @@ -0,0 +1,30 @@ +There are two types of data requests, hourly and monthly. Hourly requests generally have 24 hours of data available for each day, except in the case of forecase ensembles which are available every three hours (i.e. 8 per day). + +Hourly and monthly requests mostly have the same variables available, except some of the variables that are only in the hourly datasets. Exceptions on the single level data can be found in table 8 of [ERA5 parameter listings](https://confluence.ecmwf.int/display/CKB/ERA5%3A+data+documentation#ERA5:datadocumentation-Table8). + +## Hourly + +With the `hourly` argument you can fetch hourly ERA5 data. +All available arguments in `era5cli` can be seen using `era5cli hourly --help`, or by going to the [reference](reference/arguments.md). + +More information on the available data and options can be found on the following pages: + + - [ERA5 hourly single levels download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels). + - [ERA5 hourly pressure levels download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels). + - [ERA5 hourly single levels preliminary back extension download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels-preliminary-back-extension). + - [ERA5 hourly pressure levels preliminary back extension download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels-preliminary-back-extension). + - [ERA5-Land hourly download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-land). + +## Monthly + +With the `monthly` argument you can fetch monthly-means of ERA5 data. +All available arguments in `era5cli` can be seen using `era5cli monthly --help`, or by going to the [reference](reference/arguments.md). + +More information on the available data and options can be found on the following pages: + + - [ERA5 monthly single levels download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels-monthly-means). + - [ERA5 monthly pressure levels download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels-monthly-means). + - [ERA5 monthly single levels preliminary back extension download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels-monthly-means-preliminary-back-extension). + - [ERA5 monthly pressure levels preliminary back extension download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels-monthly-means-preliminary-back-extension). + - [ERA5-Land monthly download page](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-land-monthly-means). + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8163c8b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +# Welcome to era5cli’s documentation! + +A command line interface to download ERA5 data from the [Copernicus Climate Data Store](https://climate.copernicus.eu/). + +With era5cli you can: + + - Download meteorological data in GRIB/NetCDF, including ERA5 data from the preliminary back extension, and ERA5-Land data. + - List and retrieve information on available variables and pressure levels + - Select multiple variables for several months and years + - Split outputs by years (and optionally months), producing a separate files instead of merging them in one file + - Download multiple files at once + - Extract data for a sub-region of the globe + +For information on how to use era5cli, please go to the [user guide](getting_started.md). \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/reference/arguments.md b/docs/reference/arguments.md new file mode 100644 index 0000000..fe6b705 --- /dev/null +++ b/docs/reference/arguments.md @@ -0,0 +1,11 @@ + +All available arguments for the hourly and monthly requests are shown below. This can also be viewed by doing `era5cli hourly --help` and `era5cli monthly --help`. + +Note that not all combinations of arguments are compatible, such as `--land` and `--ensemble`. + +More information on the different variables is available in the [variable overview](variables.md). + + diff --git a/docs/reference/cli_usage.md b/docs/reference/cli_usage.md new file mode 100644 index 0000000..fde8797 --- /dev/null +++ b/docs/reference/cli_usage.md @@ -0,0 +1,11 @@ +If at any point you are in doubt about `era5cli` commands, you can use `--help` to get more information. + +For example, `era5cli hourly --help`, will show you all information about hourly-data requests. + +All different positional arguments are show below. If you want more information on the hourly and monthly requests, look at the [argument overview](arguments.md). For more information on the `info` command, and all variables, see the [variable overview](variables.md). + +### Available positional arguments: + + diff --git a/docs/reference/variables.md b/docs/reference/variables.md new file mode 100644 index 0000000..f5b4e04 --- /dev/null +++ b/docs/reference/variables.md @@ -0,0 +1,16 @@ +For ease of searching, an overview of all available variables is shown below. These can also be displayed using the `name` argument, for more information look [here](../formulating_requests.md#using-the-info-command). + +???+ tip + With the built-in `grep` command, you can also search through the lists of different variables in era5cli, for example: + + ``` + era5cli info "2Dvars" | grep temperature + ``` + + will list all single level variables that contain the word 'temperature'. + +### Lists of variables + + diff --git a/docs/source/api.rst b/docs/source/api.rst deleted file mode 100644 index 197ddb9..0000000 --- a/docs/source/api.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _api: - -API -============ - -.. contents:: - :local: - :depth: 1 - -era5cli.info -~~~~~~~~~~~~ -.. automodule:: info - :members: - :undoc-members: - :show-inheritance: - -era5cli.fetch -~~~~~~~~~~~~~ -.. automodule:: fetch - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/changes.rst b/docs/source/changes.rst deleted file mode 100644 index 09929fe..0000000 --- a/docs/source/changes.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../CHANGELOG.rst diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 5c52e65..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,65 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -sys.path.insert(0, os.path.abspath(".")) -sys.path.insert(0, os.path.abspath("../../era5cli")) - -source_suffix = ".rst" -master_doc = "index" - -# -- Project information ----------------------------------------------------- - -project = "era5cli" -copyright = "2019, Netherlands eScience Center" -author = "era5cli team" - -# The full version, including alpha/beta/rc tags -release = "1.3.2" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.viewcode", - "sphinx.ext.coverage", - "sphinx.ext.mathjax", - "sphinx.ext.napoleon", - "sphinxarg.ext", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 17c48e0..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,34 +0,0 @@ -Welcome to era5cli's documentation! -=================================== -.. include:: ../../README.rst - :start-after: inclusion-marker-start-do-not-remove - :end-before: inclusion-marker-end-do-not-remove - -Content -~~~~~~~ - -.. toctree:: - :maxdepth: 2 - - installation - instructions - api - - -Indices and tables -~~~~~~~~~~~~~~~~~~ - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - - -Meta Information -~~~~~~~~~~~~~~~~ - -.. toctree:: - :maxdepth: 1 - - contribute - changes - license diff --git a/docs/source/installation.rst b/docs/source/installation.rst deleted file mode 100644 index 7dc4923..0000000 --- a/docs/source/installation.rst +++ /dev/null @@ -1,30 +0,0 @@ -Installation ------------- - -Install from PyPI -~~~~~~~~~~~~~~~~~ -era5cli is available as a package in `PyPI `_. - -To install from PyPI, use the following command: -:: - - pip install era5cli - -Install with conda -~~~~~~~~~~~~~~~~~~ -era5cli has been packaged for conda-forge. It can be installed from there with: -:: - - conda install era5cli -c conda-forge - -The current version that will be installed via conda-forge is: - -.. image:: https://anaconda.org/conda-forge/era5cli/badges/version.svg - :target: https://anaconda.org/conda-forge/era5cli - -Install from GitHub -~~~~~~~~~~~~~~~~~~~ -The development version is available via GitHub. To install directly from GitHub, the following command can be used: -:: - - pip install -U git+https://github.com/eWaterCycle/era5cli.git diff --git a/docs/source/instructions.rst b/docs/source/instructions.rst deleted file mode 100644 index 4a1fb3d..0000000 --- a/docs/source/instructions.rst +++ /dev/null @@ -1,101 +0,0 @@ -Instructions ------------- - -Register at Copernicus Climate Data Service -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- You have to register at Copernicus Climate Data Service: - `copernicus `__. - After activating your account use your new account to log in. In you - profile page you can find your user ID and your API key. - -- Copy your user ID and API key. - -Configure era5cli to use your ID and key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To configure era5cli to use your ID and API key, do: -:: - - era5cli config --uid ID_NUMBER --key "KEY" - - -Where ID_NUMBER is your user ID (e.g. ``123456``) and "KEY" is your API key, inside double quotes (e.g. ``"4s215sgs-2dfa-6h34-62h2-1615ad163414"``). - -After running this command your ID and key are validated and stored inside your home folder, under ``.config/era5cli.txt``. You can also edit this file manually. - - -Info on available variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. argparse:: - :module: era5cli.cli - :func: _build_parser - :prog: era5cli - :path: info - -Tip: search in variables -######################## - -To quickly search the list of variables for a specific word, you can use the -built-in ``grep`` command. For example: - -:: - - era5cli info "2Dvars" | grep temperature - - -should list all single level variables that contain the word 'temperature', so -they can be easily identified for an era5cli request. - -Running era5cli from the command line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -era5cli can be used to fetch both hourly data and monthly averaged data. - -Fetching hourly data -#################### - -Fetch hourly data through an cdsapi call via command line. More information on the available data and options can be found on: - -| `Era5 hourly single levels download page `_. -| `Era5 hourly pressure levels download page `_. -| `Era5 hourly single levels preliminary back extension download page `_. -| `Era5 hourly pressure levels preliminary back extension download page `_. -| `Era5-Land hourly download page `_. - - -.. argparse:: - :module: era5cli.cli - :func: _build_parser - :prog: era5cli - :path: hourly - - -Fetching monthly data -##################### - -Fetch monthly data through an cdsapi call via command line. More information on the available data and options can be found on: - -| `Era5 monthly single levels download page `_. -| `Era5 monthly pressure levels download page `_. -| `Era5 monthly single levels preliminary back extension download page `_. -| `Era5 monthly pressure levels preliminary back extension download page `_. -| `Era5-Land monthly download page `_. - - -For the monthly data, some of the variables are not available. Exceptions on the single level data can be found in table 8 of -`ERA5 parameter listings `_ - -.. argparse:: - :module: era5cli.cli - :func: _build_parser - :prog: era5cli - :path: monthly - - -Removing or canceling requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ERA-5 download requests will be saved in the `Your requests `_ section in your profile on the Copernicus Climate Data Store. Here you can re-download the requested data, cancel active requests, or remove old requests. - -Note that it is currently not possible to cancel active requests from the command line: Killing the process will not download the data to your local machine but still add it to your Copernicus account. diff --git a/docs/source/license.rst b/docs/source/license.rst deleted file mode 100644 index bef6801..0000000 --- a/docs/source/license.rst +++ /dev/null @@ -1,4 +0,0 @@ -License -******* - -.. include:: ../../LICENSE diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..9f84e28 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,4 @@ +/* Change the color of the footer from the (default) black */ +.md-footer { + background-color: var(--md-typeset-a-color); +} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..9a0e92b --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,73 @@ +site_name: era5cli documentation +repo_url: https://github.com/eWaterCycle/era5cli +repo_name: era5cli +extra_css: + - stylesheets/extra.css + +nav: + - Home: index.md + - "User Guide": + - Getting started: getting_started.md + - Formulating requests: formulating_requests.md + - Dataset overview: hourly_monthly.md + - "CLI Reference": + - CLI usage: reference/cli_usage.md + - Argument overview: reference/arguments.md + - Variable overview: reference/variables.md + - "Contributing": + - contribute.md + - "Developer Documentation": + - dev.md + - "Changelog": + - CHANGELOG.md + +theme: + name: material + logo: assets/era5cli_logo_colors.png + favicon: assets/era5cli_favicon.png + features: + - navigation.sections + - navigation.instant + - navigation.tabs + - navigation.tabs.sticky + - navigation.footer + - navigation.path + - content.code.copy + - search.suggest + icon: + repo: fontawesome/brands/github-alt + + palette: + # Palette toggle for light mode + - scheme: default + toggle: + icon: material/weather-sunny + name: Switch to dark mode + primary: blue + accent: dark blue + + # Palette toggle for dark mode + - scheme: slate + toggle: + icon: material/weather-night + name: Switch to light mode + primary: indigo + accent: dark blue + +plugins: +- search: + lang: en +- gen-files: + scripts: + - docs/gen_reference_pages.py + +extra: + generator: true + +markdown_extensions: + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - tables + - admonition + - pymdownx.details diff --git a/pyproject.toml b/pyproject.toml index 7549907..dc5f453 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,7 +11,7 @@ path = "era5cli/__version__.py" [project] name = "era5cli" description = "A command line interface to download ERA5 data from the Copernicus Climate Data Store. https://climate.copernicus.eu/.." -readme = "README.rst" +readme = "README.md" license = { text = "Apache Software License" } requires-python = ">=3.7" authors = [ @@ -35,6 +35,9 @@ authors = [ ] keywords = [ "ERA-5", + "climate data", + "cds api", + "cds download", ] classifiers = [ "Development Status :: 5 - Production/Stable", @@ -75,7 +78,11 @@ dev = [ "pytest-flake8", "pytest-cov", ] -docs = ["Sphinx", "sphinx-argparse", "sphinx_rtd_theme",] # Required for readthedocs +docs = [ + "mkdocs", + "mkdocs-material", + "mkdocs-gen-files", +] [tool.pytest.ini_options] testpaths = ["tests"] @@ -97,7 +104,8 @@ coverage = ["pytest --cov=era5cli --cov-report term --cov-report xml:cov.xml tes features = ["docs",] [tool.hatch.envs.docs.scripts] -build = ["sphinx-build docs/source docs/build",] +build = ["mkdocs build",] +serve = ["mkdocs serve",] [tool.black] line-length = 88 diff --git a/readthedocs.yml b/readthedocs.yml index f46aae3..e28c1a6 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -5,6 +5,10 @@ build: tools: python: "3.9" +mkdocs: + configuration: mkdocs.yml + fail_on_warning: false + python: install: - method: pip