Update documentation all over the place (earthobservations#150)

.gitignore

@@ -8,4 +8,5 @@ coverage.xml
 .coverage
 htmlcov
 .nox/
-.pytest_cache/
+.pytest_cache/
+docs/_build/

CHANGELOG.rst

@@ -2,11 +2,11 @@ Changelog
 *********
 
 Development
-=======
+===========
 
-- add test for Jupyter notebook
-- add function to discover available climate observations (time resolution, parameter,
-period type)
+- Add test for Jupyter notebook
+- Add function to discover available climate observations
+  (time resolution, parameter, period type)
 
 0.6.0 (07.09.2020)
 ==================

README.rst

@@ -1,5 +1,6 @@
-Introduction to wetterdienst
-############################
+#################################################################
+Wetterdienst - Python library to ease access to open weather data
+#################################################################
 
 .. image:: https://github.com/earthobservations/wetterdienst/workflows/Tests/badge.svg
    :target: https://github.com/earthobservations/wetterdienst/actions?workflow=Tests
@@ -26,95 +27,119 @@ Introduction to wetterdienst
    :target: https://zenodo.org/badge/latestdoi/160953150
 
 
-Welcome to wetterdienst, your friendly weather service library for Python from the
-neighbourhood! We are a group of people, who try to make access to weather data in
+Welcome to Wetterdienst, your friendly weather service library for Python from the
+neighbourhood! We are a group of people who try to make access to weather data in
 Python feel like a warm summer breeze, similar to other projects like
 `rdwd <https://github.com/brry/rdwd>`_
-for the R language ,which originally drew our interest in this project. As we long-term
-goal is to provide you with data from multiple weather services, we are still stuck with
-the German Weather Service (DWD).
+for the R language, which originally drew our interest in this project.
 
-We currently cover
+While our long-term goal is to provide you with data from multiple weather services,
+we are still stuck with the German Weather Service (DWD).
 
-- historical weather data from ground stations
-- RADOLAN fitted radar data for areal precipitation
+Features
+********
 
-and soon
+Coverage
+========
+The library currently covers
 
+- historical weather data from ground stations
+- RADOLAN fitted radar data for areal precipitation
 - MOSMIX statistical optimized scalar forecasts extracted from weather models
 
-
 To get better insight on which data we have currently made available, with this library
-take a look at
-`Data Coverage <https://wetterdienst.readthedocs.io/en/latest/pages/data_coverage.html>`_
-.
-
-**CAUTION**
-Although the data is specified as being open, the DWD asks you to reference them as
-Copyright owner. To check out further, take a look at the
-`Open Data Strategy at the DWD <https://www.dwd.de/EN/ourservices/opendata/opendata.html>`_
-and the
-`Official Copyright <https://www.dwd.de/EN/service/copyright/copyright_artikel.html?nn=495490&lsbId=627548>`_
+take a look at `data coverage`_.
 
-To keep you updated about added features etc. we provide a
-`Changelog <https://wetterdienst.readthedocs.io/en/latest/pages/development.html#current>`_
-.
+.. _data coverage: https://wetterdienst.readthedocs.io/en/latest/pages/data_coverage.html
 
-We strongly recommend reading the full documentation, which will be updated continuously
-as we make progress with this library:
-https://wetterdienst.readthedocs.io/en/latest/
+Details
+=======
+- Get metadata for a set of Parameter, PeriodType and TimeResolution.
+- Get station(s) nearby a selected location for a given set.
+- Store/recover collected data.
+- Docker image to run the library dockerized.
+- Client to run the library from command line.
 
-Getting started
-***************
 
-Run the following to make wetterdienst available in your current environment:
+Setup
+*****
+Run the following to make ``wetterdienst`` available in your current environment:
 
-.. code-block:: Python
+.. code-block:: bash
 
     pip install wetterdienst
 
-To get some historical observed station data call
+Synopsis
+********
+Get historical data for specific stations, using Python:
 
-.. code-block:: Python
+.. code-block:: python
 
-    from wetterdienst import collect_dwd_data
-    from wetterdienst import Parameter, PeriodType, TimeResolution
+    from wetterdienst import DWDStationRequest, Parameter, PeriodType, TimeResolution
 
-    station_data = collect_dwd_data(
-        station_ids=[1048],
-        parameter=Parameter.CLIMATE_SUMMARY,
+    request = DWDStationRequest(
+        station_ids=[1048,4411],
+        parameter=[Parameter.CLIMATE_SUMMARY, Parameter.SOLAR],
         time_resolution=TimeResolution.DAILY,
-        period_type=PeriodType.HISTORICAL
+        start_date="1990-01-01",
+        end_date="2020-01-01",
+        tidy_data=True,
+        humanize_column_names=True,
+        write_file=True,
+        prefer_local=True
     )
 
-Furthermore we currently offer:
+    for df in request.collect_data():
+        # analyse the station here
+
+Get data for specific stations from the command line:
 
-- RADOLAN radar based precipitation for Germany
-- getting metadata for a set of Parameter, PeriodType and TimeResolution
-- getting station(s) nearby a selected location for a given set...
+.. code-block:: bash
 
-and also
+    # Get list of all stations for daily climate summary data in JSON format
+    wetterdienst stations --parameter=kl --resolution=daily --period=recent
 
-- storing/recovering collected data
-- a prepared Docker image to run the library dockerized
-- a client to run the library from command line
+    # Get daily climate summary data for specific stations
+    wetterdienst readings --station=1048,4411 --parameter=kl --resolution=daily --period=recent
+
+
+Documentation
+*************
+We strongly recommend reading the full documentation, which will be updated continuously
+as we make progress with this library:
+
+    - https://wetterdienst.readthedocs.io/
+
+For the whole functionality, check out the `Wetterdienst API`_ section of our
+documentation, which will be constantly updated. To stay up to date with the
+development, take a look at the changelog_. Also, don't miss out our examples_.
+
+
+.. _Wetterdienst API: https://wetterdienst.readthedocs.io/en/latest/pages/api.html
+.. _changelog: https://wetterdienst.readthedocs.io/en/latest/pages/api.html
+.. _examples: https://github.com/earthobservations/wetterdienst/tree/master/example
 
-For the whole functionality, check out the
-`API <https://wetterdienst.readthedocs.io/en/latest/pages/api.html>`_
-section of our documentation, which will be constantly updated. Also don't miss out our
-`examples <https://github.com/earthobservations/wetterdienst/tree/master/example>`_.
 
 Contribution
 ************
-
 Check out our contribution section in the documentation! For a successful PR passing
 all tests, you have to run
 
-.. code-block:: Python
+.. code-block:: bash
 
     nox -s tests
     nox -s black
     nox -s lint
 
 before committing. This will inform you in case of problems with tests and your code
 format.
+
+
+Data license
+************
+**CAUTION**
+Although the data is specified as being open, the DWD asks you to reference them as
+Copyright owner. To check out further, take a look at the
+`Open Data Strategy at the DWD <https://www.dwd.de/EN/ourservices/opendata/opendata.html>`_
+and the
+`Official Copyright <https://www.dwd.de/EN/service/copyright/copyright_artikel.html?nn=495490&lsbId=627548>`_.

docs/index.rst

@@ -3,20 +3,25 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-****************************************
-Welcome to wetterdienst's documentation!
-****************************************
+#################################################################
+Wetterdienst - Python library to ease access to open weather data
+#################################################################
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
 
-   pages/welcome
+   README <pages/welcome>
    pages/installation
    pages/data_coverage
    pages/api
+   pages/cli
+
+.. toctree::
+   :maxdepth: 1
+
    pages/behind_the_scenes
    pages/development
+   pages/changelog
    pages/license_and_citation
 
 Indices and tables