Move docs to mkdocs, update user documentation (eWaterCycle#142)

* Move docs to mkdocs and update them

* Add favicon

* Move changelog to markdown

* Add comments to gen_reference_pages. Apply format

* Apply suggestions from code review

Co-authored-by: Peter Kalverla <peter.kalverla@gmx.com>

* Incorporate Peter's comments

* Update .gitignore for mkdocs

---------

Co-authored-by: Peter Kalverla <peter.kalverla@gmx.com>

.gitignore

@@ -73,6 +73,9 @@ docs/doctrees/
 docs/html/
 docs/build/
 
+# mkdocs
+site/
+
 # External Sources
 #src/external
 src/

README.md

@@ -0,0 +1,33 @@
+<img align="right" width="150" alt="Logo" src="docs/assets/era5cli_logo_colors_border.png">
+
+
+[![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](<https://climate.copernicus.eu/>).
+
+<hr>
+
+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
+
+<hr>
+
+Free software: Apache Software License 2.0
+
+Documentation: https://era5cli.readthedocs.io
+

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.

docs/source/contribute.rst → 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 <https://github.com/ewatercycle/era5cli/issues>`_.
+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
+```

docs/dev.md

@@ -0,0 +1 @@
+TODO