feature: added basic github page info

.github/workflows/github-pages-deployment.yml

@@ -0,0 +1,29 @@
+name: GitHub Pages Deployment
+on:
+  push:
+    branches:
+      main*
+permissions:
+  id-token: write
+  pages: write
+jobs:
+  # ---------------------------------------------------------------- #
+  # |  Building and deployment of Sphinx build                     | #
+  # ---------------------------------------------------------------- #
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install Dependencies
+        run: |
+          pip install sphinx piccolo-theme myst_parser
+      - name: Sphinx Build
+        run: |
+          sphinx-build ./sphinx-docs/ _build
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v2.0.0
+        with:
+          path: _build
+      - name: Push artifact to pages
+        uses: actions/deploy-pages@v3.0.1

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "weather_provider_api"
-version = "2.54.0"
+version = "2.55.0"
 description = "Weather Provider Libraries and API"
 authors = ["Verbindingsteam", "Raoul Linnenbank <58594297+rflinnenbank@users.noreply.github.com>"]
 license = "MPL-2.0"
@@ -12,24 +12,24 @@ include = [
 
 [tool.poetry.dependencies]
 python = ">=3.10,<3.12"
-fastapi = "^0.110.2"
-requests = "^2.31.0"
+fastapi = "^0.112.1"
+requests = "^2.32.3"
 geopy = "^2.3.0"
 numpy = "^1.26.2"
-gunicorn = "^22.0.0"
-lxml = "^5.2.1"
+gunicorn = "^23.0.0"
+lxml = "^5.3.0"
 starlette-prometheus = "^0.9.0"
 beautifulsoup4 = "^4.12.2"
-netcdf4 = "^1.6.5"
+netcdf4 = "^1.7.1"
 tomli = "^2.0.1"
 pandas = "^2.1.3"
-xarray = "^2024.3.0"
-cfgrib = "^0.9.10.4"
-uvicorn = "^0.29.0"
+xarray = "^2024.7.0"
+cfgrib = "^0.9.14.0"
+uvicorn = "^0.30.6"
 slowapi = "^0.1.7"
 loguru = "^0.7.2"
-email-validator = "^2.1.0.post1"
-eccodes = "^1.6.1"
+email-validator = "^2.2.0"
+eccodes = "^1.7.1"
 ecmwflibs = "0.6.3"
 accept-types = "^0.4.1"
 
@@ -42,6 +42,10 @@ pytest-cov = "^5.0.0"
 pylint = "^3.1.0"
 black = "^24.4.0"
 ruff = {version = "^0.4.1", source = "pypi"}
+pytest = "^8.3.2"
+sphinx = "^8.0.2"
+myst-parser = "^4.0.0"
+piccolo-theme = "^0.23.0"
 
 [tool.poetry.scripts]
 wpla_update_era5sl = "weather_provider_api.scripts.update_era5sl_repository:main"

sphinx-docs/Makefile

@@ -0,0 +1,20 @@
+# 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     = .
+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)

sphinx-docs/conf.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+
+#  SPDX-FileCopyrightText: 2019-2024 Alliander N.V.
+#  SPDX-License-Identifier: MPL-2.0
+
+import os
+import sys
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "Weather Provider API"
+copyright = "2024, Alliander"
+author = "Raoul Linnenbank"
+release = "0.7.0"
+
+highlight_language = "python3"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser", "sphinx.ext.autodoc"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+
+html_theme = "piccolo_theme"
+html_static_path = ["_static"]
+
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+
+# Don't show class signature with the class' name.
+autodoc_class_signature = "separated"
+
+add_module_names = False
+show_authors = True
+toc_object_entries_show_parents = "hide"

sphinx-docs/index.rst

@@ -0,0 +1,37 @@
+.. coding=utf-8
+.. Weather Provider Libraries documentation master file, created by
+   sphinx-quickstart on Wed Oct  4 21:03:43 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+##############################################################
+Welcome to the Weather Provider API (WPA) documentation!
+##############################################################
+
+.. image:: /_static/wpas_logo.svg
+    :alt: Weather Provider Access Suite
+    :align: center
+    :width: 480px
+
+.. include:: introduction.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   self
+
+.. toctree::
+   :caption: Basic Information
+   :maxdepth: 3
+
+   introduction
+   quick-start
+   weather_provider_access_suite_info_page
+
+.. toctree::
+   :caption: Modular information
+   :maxdepth: 3
+   :hidden:
+
+   modules
+   modindex

sphinx-docs/introduction.rst

@@ -0,0 +1,88 @@
+.. coding=utf-8
+.. SPDX-FileCopyrightText: 2019-2023 Alliander N.V.
+.. SPDX-License-Identifier: MPL-2.0
+
+**********************************************
+An introduction to the Weather Provider API V2
+**********************************************
+
+    "NOTE: The follow-up project to the Weather Provider APi V2 is currently under development.
+     For more information on the new project, please check the "Weather Provider Access Suite" project information at:
+     :ref:`Weather Provider Access Suite Info Page`"
+
+=============================================
+What is the Weather Provider API (WPA)?
+=============================================
+
+----------------
+**Project Goal**
+----------------
+The Weather Provider Libraries project is a project with a singular goal in mind::
+
+    Easily accessing any data for a multitude of meteorological datasets and meteorological site-pages
+    without any prior knowledge of those datasets or even their specific content.
+
+That is right. Without any prior knowledge of a supported dataset itself, we want you to be able to achieve the
+following:
+
+* *Make requests for specific periods and meteorological factors.*
+* *Transform the received data into one of several supported uniform formats, allowing for comparison of data between
+  datasets if the fields are identical in nature.*
+* *Transform the output for those requests into a wide number of commonly used file formats, flattening the output from
+  multi-dimensional data as needed.*
+* *Translate existing dataset output directly into the aforementioned supported uniform data and allow for outputting
+  that result in the supported output file formats as well.*
+
+**As a secondary goal, we also wish to achieve the following:**
+
+*   For motivated people that have knowledge or affinity with unsupported datasets to build their own compatible model(s)
+    and source(s) without prior knowledge of the WPL system by being guided by the base classes themselves.
+    This will follow in the upcoming format of the Weather Provider API, the Weather Provider Access Suite Project.
+
+*   Allow for the easy access and plugging of sources and models as desired. You can access the data you want to use
+    without any need for installing more than just a singular source and calling more than just the model you need if
+    that is what you need, while also retaining the possibility to upscale to a multitude of sources and models and
+    even connect those to the `Weather Provider API`_ project for a fully functional API based on your wishes.
+
+===============
+Project Origins
+===============
+
+The Weather Provider Libraries Project, or WPL, as it will be abbreviated a lot in the documentation of this project,
+is a project based on the original "**weather_provider_api**" project found at:
+
+ `https://github.com/alliander-opensource/weather-provider-api/ <https://github.com/alliander-opensource/weather-provider-api/>`_
+
+Until version 3.0 of this project, every component thereof was considered a part of a singular whole, but to allow for
+easier usage and the easier building of new models and sources, the project was split up into three components:
+
+---------------------------------
+**1. Weather Provider Libraries**
+---------------------------------
+
+   This project and the part that holds all of the common components and tools responsible for formatting, processing
+   and transforming meteorological data, as well as all of the base classes for creating Models and Sources for the
+   project. Finally the project also houses the Controller which allows for easy configuration and acquisition of data
+   over multiple sources and models.
+
+---------------------------
+**2. Weather Provider API**
+---------------------------
+
+   This project houses the API implementation of this project. It uses the Weather Provider Libraries project to
+   transform any connected source and model into appropriate endpoints. This fully functional FastAPI implementation is
+   fully supportive of the OpenAPI standard and can easily be scaled according to your wishes. The project repository
+   even comes with a number of example deployment folders. The project can be used via custom deployment through its
+   package or deployment using the readily available Docker images.
+   For more information on this project please check the Project's repository page at: `Weather Provider API`_
+
+-------------------------------
+**3. Weather Provider Sources**
+-------------------------------
+
+   This project actually consists of multiple repositories. Each repository houses one or multiple Sources that can be
+   installed as packages used separately or from a Weather Provider Libraries system. Each Source can house one or
+   multiple Models, each representing a specific meteorological dataset, site-page with meteorological data, or fusion
+   thereof.
+
+.. _Weather Provider API: https://github.com/alliander-opensource/weather-provider-api

sphinx-docs/modules.rst

@@ -0,0 +1,7 @@
+weather_provider_api
+====================
+
+.. toctree::
+   :maxdepth: 4
+
+   weather_provider_api

sphinx-docs/quick-start.rst

@@ -0,0 +1,50 @@
+.. coding=utf-8
+
+***************************************************
+Getting Started with the Weather Provider Libraries
+***************************************************
+
+====================
+Package installation
+====================
+To install the Weather Provider Libraries package you only need to install it using PyPi::
+
+>  pip install weather-provider-libraries
+
+*Please note that when building your own model(s) and source(s) you will need to use the base classes declared
+within the package to allow them to be recognized and used by the API.*
+
+==========================
+Default Sources and Models
+==========================
+The Weather Provider Libraries (WPL) package will automatically install a number of sources and models natively
+supported by the project. For a information on these sources, their models and their specific usage, please read the
+documentation available at:
+
+    `https://github.com/alliander-opensource/ <https://github.com/alliander-opensource/>`_
+
+===========================================
+Your first request using the WPL Controller
+===========================================
+When using WPL directly, rather than through the API, you'll be able to contact all configured and set models by using
+the Controller. The controller can be either instantiated by using Python or called upon via one of the available
+scripts.
+
+.. code-block::
+   :caption: **Python instantiation of the Controller:**
+
+       from weather_provider_libraries.wpl_controller import WPLController
+
+       controller = WPLController()
+
+*Usually your IDE should be able to pick up on the possible requests and options available to this object. If unsure or
+if you wish for more information, please check the module documentation as well.*
+
+
+.. code-block::
+   :caption: **Script activation of the controller:**
+
+       python run wpl_controller_commands
+
+*This script should retrieve a list of known WPL Controller commands that can be executed directly from the command line
+and their accepted parameters*