68 improve docs (#70)

* updated theme * remove duplicated makefile
Deltares · Mar 12, 2024 · 85e4c7b · 85e4c7b
1 parent 09809c0
commit 85e4c7b
Show file tree

Hide file tree

Showing 12 changed files with 57 additions and 176 deletions.
diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml
diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -1,9 +1,6 @@
 # ddlpy
 
 [![pypi-image](https://img.shields.io/pypi/v/ddlpy.svg)](https://pypi.python.org/pypi/ddlpy)
-[![image](https://img.shields.io/travis/deltares/ddlpy.svg)](https://travis-ci.org/deltares/ddlpy)
-[![Documentation Status](https://readthedocs.org/projects/rws-ddlpy/badge/?version=latest)](https://rws-ddlpy.readthedocs.io/en/latest/?badge=latest)
-[![Updates](https://pyup.io/repos/github/deltares/ddlpy/shield.svg)](https://pyup.io/repos/github/deltares/ddlpy/)
 [![pytest](https://github.com/Deltares/ddlpy/actions/workflows/pytest.yml/badge.svg?branch=main)](https://github.com/Deltares/ddlpy/actions/workflows/pytest.yml)
 [![codecov](https://img.shields.io/codecov/c/github/deltares/ddlpy.svg?style=flat-square)](https://app.codecov.io/gh/deltares/ddlpy?displayType=list)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Deltares_ddlpy&metric=alert_status)](https://sonarcloud.io/summary/overall?id=Deltares_ddlpy)
@@ -12,9 +9,7 @@
 
 (D)ata (D)istributie (L)aag is a service from Rijkswaterstaat for distributing water quantity data. This package provides an API for python.
 
-Service from Rijkswaterstaat for distributing water quantity data.
-
--   Documentation: <https://ddlpy.readthedocs.io>.
+Documentation: <https://deltares.github.io/ddlpy>
 
 See also https://github.com/wstolte/rwsapi for the R API.
 

diff --git a/ddlpy/waterinfo.py b/ddlpy/waterinfo.py
@@ -1,21 +1,22 @@
+# -*- coding: utf-8 -*-
+
 import pandas as pd
 import xarray as xr
 from datetime import datetime, timedelta
 import pytz
 
-
-def waterinfo_read(f, encoding='latin'):
-    """Load RWS csv data of https://waterinfo.rws.nl into xarray
 
+def waterinfo_read(f, encoding='latin'):
+    """
+    Load RWS csv data of https://waterinfo.rws.nl into xarray
+    
     Can handle two types of files
-    * direct download from https://waterinfo.rws.nl
-      first column is 'Datum'
-    * request via https://waterinfo.rws.nl for link per email
-      first column is 'MONSTER_IDENTIFICATIE'
-      If multiple variables are present, a list of xarrays is returned.
+    - direct download from https://waterinfo.rws.nl, first column is 'Datum'
+    - request via https://waterinfo.rws.nl for link per email, first column is 'MONSTER_IDENTIFICATIE'
+    If multiple variables are present, a list of xarrays is returned.
     
     An xarray that can be transformed into a dataframe:
-     
+    
     TIMEZONE
     The time is converted to 'UTC' from 
     * 'CET' (default) for direct downloads
@@ -28,12 +29,13 @@ def waterinfo_read(f, encoding='latin'):
     october, and UTC+1) rest of the year) whereas the historic
     % data download in the website part (via "Download meer data" )
     are always UTC+1 (no Daylight Saving Time applied).
-
+    
     Example:
     >> ds = waterinfo_read('x.csv',tzone='UTC+1')
     >> df = ds.to_dataframe()
     >> df.head()
-     """    
+    
+    """
 
     dfall = pd.read_csv(f,delimiter=';', encoding=encoding)
 
@@ -58,8 +60,8 @@ def waterinfo_read(f, encoding='latin'):
         print(len(df),' rows for variable: ',variable)
 
         if 'WAARNEMINGDATUM' in df.keys():
-#MONSTER_IDENTIFICATIE;MEETPUNT_IDENTIFICATIE;TYPERING_OMSCHRIJVING;TYPERING_CODE;GROOTHEID_OMSCHRIJVING;GROOTHEID_ CODE;PARAMETER_OMSCHRIJVING;PARAMETER_ CODE;EENHEID_CODE;HOEDANIGHEID_OMSCHRIJVING;HOEDANIGHEID_CODE;COMPARTIMENT_OMSCHRIJVING;COMPARTIMENT_CODE;WAARDEBEWERKINGSMETHODE_OMSCHRIJVING;WAARDEBEWERKINGSMETHODE_CODE;WAARDEBEPALINGSMETHODE_OMSCHRIJVING;WAARDEBEPALINGSMETHODE_CODE;BEMONSTERINGSSOORT_OMSCHRIJVING;BEMONSTERINGSSOORT_CODE;WAARNEMINGDATUM;WAARNEMINGTIJD;LIMIETSYMBOOL;NUMERIEKEWAARDE;ALFANUMERIEKEWAARDE;KWALITEITSOORDEEL_CODE;STATUSWAARDE;OPDRACHTGEVENDE_INSTANTIE;MEETAPPARAAT_OMSCHRIJVING;MEETAPPARAAT_CODE;BEMONSTERINGSAPPARAAT_OMSCHRIJVING;BEMONSTERINGSAPPARAAT_CODE;PLAATSBEPALINGSAPPARAAT_OMSCHRIJVING;PLAATSBEPALINGSAPPARAAT_CODE;BEMONSTERINGSHOOGTE;REFERENTIEVLAK;EPSG;X;Y;ORGAAN_OMSCHRIJVING;ORGAAN_CODE;TAXON_NAME
-#;Scheveningen;;;Waterhoogte berekend;WATHTBRKD;;;cm;t.o.v. Normaal Amsterdams Peil;NAP;Oppervlaktewater;OW;;;Astronomische waterhoogte mbv harmonische analyse;other:F012;;;01-05-2020;00:00:00;;-44;;Normale waarde;Ongecontroleerd;RIKZMON_WAT;;;;;;;-999999999;NVT;25831;586550,994420996;5772806,43069697;;;
+            #MONSTER_IDENTIFICATIE;MEETPUNT_IDENTIFICATIE;TYPERING_OMSCHRIJVING;TYPERING_CODE;GROOTHEID_OMSCHRIJVING;GROOTHEID_ CODE;PARAMETER_OMSCHRIJVING;PARAMETER_ CODE;EENHEID_CODE;HOEDANIGHEID_OMSCHRIJVING;HOEDANIGHEID_CODE;COMPARTIMENT_OMSCHRIJVING;COMPARTIMENT_CODE;WAARDEBEWERKINGSMETHODE_OMSCHRIJVING;WAARDEBEWERKINGSMETHODE_CODE;WAARDEBEPALINGSMETHODE_OMSCHRIJVING;WAARDEBEPALINGSMETHODE_CODE;BEMONSTERINGSSOORT_OMSCHRIJVING;BEMONSTERINGSSOORT_CODE;WAARNEMINGDATUM;WAARNEMINGTIJD;LIMIETSYMBOOL;NUMERIEKEWAARDE;ALFANUMERIEKEWAARDE;KWALITEITSOORDEEL_CODE;STATUSWAARDE;OPDRACHTGEVENDE_INSTANTIE;MEETAPPARAAT_OMSCHRIJVING;MEETAPPARAAT_CODE;BEMONSTERINGSAPPARAAT_OMSCHRIJVING;BEMONSTERINGSAPPARAAT_CODE;PLAATSBEPALINGSAPPARAAT_OMSCHRIJVING;PLAATSBEPALINGSAPPARAAT_CODE;BEMONSTERINGSHOOGTE;REFERENTIEVLAK;EPSG;X;Y;ORGAAN_OMSCHRIJVING;ORGAAN_CODE;TAXON_NAME
+            #;Scheveningen;;;Waterhoogte berekend;WATHTBRKD;;;cm;t.o.v. Normaal Amsterdams Peil;NAP;Oppervlaktewater;OW;;;Astronomische waterhoogte mbv harmonische analyse;other:F012;;;01-05-2020;00:00:00;;-44;;Normale waarde;Ongecontroleerd;RIKZMON_WAT;;;;;;;-999999999;NVT;25831;586550,994420996;5772806,43069697;;;
 
             t = [datetime.strptime(t,'%d-%m-%Y%H:%M:%S') for t in df['WAARNEMINGDATUM']+df['WAARNEMINGTIJD']]
 
@@ -76,8 +78,8 @@ def waterinfo_read(f, encoding='latin'):
                         'EPSG','X','Y']        
 
         elif 'Datum' in df.keys():
-#Datum;Tijd;Parameter;Locatie;Meting;Verwachting;Astronomisch getijden;Eenheid;Bemonsteringshoogte;Referentievlak;
-#5-5-2020;21:10:00;Waterhoogte Oppervlaktewater t.o.v. Normaal Amsterdams Peil in cm;Den Helder;-1;;;cm;-999999999;NAP;
+            #Datum;Tijd;Parameter;Locatie;Meting;Verwachting;Astronomisch getijden;Eenheid;Bemonsteringshoogte;Referentievlak;
+            #5-5-2020;21:10:00;Waterhoogte Oppervlaktewater t.o.v. Normaal Amsterdams Peil in cm;Den Helder;-1;;;cm;-999999999;NAP;
 
             # handle trailing ;
             df = df.loc[:, ~df.columns.str.contains('^Unnamed')]

diff --git a/docs/_static/deltares-white.svg b/docs/_static/deltares-white.svg
diff --git a/docs/_static/deltares.svg b/docs/_static/deltares.svg
diff --git a/docs/_static/enabling-delta-life.svg b/docs/_static/enabling-delta-life.svg
diff --git a/docs/_static/theme-deltares.css b/docs/_static/theme-deltares.css
@@ -0,0 +1,4 @@
+/* enlarge deltares & github icon size; only works with local/url svg files; not with fa icons */
+img.icon-link-image {
+    height: 2.5em !important;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,7 +32,7 @@
 
 # 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']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_mdinclude']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -47,7 +47,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Data Distributie Laag. Service from Rijkswaterstaat for distributing water quantity data.'
+project = u'ddlpy'
 copyright = u"2019, Fedor Baart"
 author = u"Fedor Baart"
 
@@ -65,7 +65,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -84,19 +84,37 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "navigation_with_keys": False,
+    "navbar_align": "content",
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/Deltares/ddlpy",  # required
+            "icon": "https://upload.wikimedia.org/wikipedia/commons/9/91/Octicons-mark-github.svg",
+            "type": "url",
+        },
+        {
+            "name": "Deltares",
+            "url": "https://deltares.nl/en/",
+            "icon": "_static/deltares-white.svg",
+            "type": "local",
+        },
+    ],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+}
 
 # 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 = ['_static']
-
+html_static_path = ["_static"]
+html_css_files = ["theme-deltares.css"]
 
 # -- Options for HTMLHelp output ---------------------------------------
 

diff --git a/docs/modules.rst b/docs/modules.rst
@@ -1,5 +1,5 @@
-ddlpy
-=====
+modules
+=========
 
 .. toctree::
    :maxdepth: 4

diff --git a/docs/readme.rst b/docs/readme.rst
@@ -1 +1 @@
-.. include:: ../README.rst
+.. mdinclude:: ../README.md