Move docs from readme to markdown files and docstring

.github/workflows/tests+pypi.yml

@@ -98,7 +98,7 @@ jobs:
           pip3 install pdoc
           pip install -e . -e ./examples
           export PDOC_ALLOW_EXEC=1
-          python -We -m pdoc -o html PyMPDATA examples/PyMPDATA_examples -t pdoc_templates
+          python -We -m pdoc -o html PyMPDATA examples/PyMPDATA_examples -t docs/templates
       - if: ${{ github.ref == 'refs/heads/main' && matrix.platform == 'ubuntu-latest' }}
         uses: JamesIves/github-pages-deploy-action@4.1.1
         with:

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ default_stages: [commit]
 
 repos:
   - repo: https://github.com/psf/black
-    rev: 24.1.1
+    rev: 24.8.0
     hooks:
       - id: black
 
@@ -15,7 +15,7 @@ repos:
         args: ["--profile", "black"]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer

PyMPDATA/__init__.py

@@ -1,11 +1,5 @@
 """
-Numba-accelerated Pythonic implementation of Multidimensional Positive Definite
-Advection Transport Algorithm (MPDATA) with examples in Python, Julia and Matlab
-
-PyMPDATA uses staggered grid with the following node placement for
-`PyMPDATA.scalar_field.ScalarField` and
-`PyMPDATA.vector_field.VectorField` elements:
-![](https://github.com/atmos-cloud-sim-uj/PyMPDATA/releases/download/tip/readme_grid.png)
+.. include:: ../docs/markdown/pympdata_landing.md
 """
 
 # pylint: disable=invalid-name

docs/markdown/pympdata_examples_landing.md

@@ -0,0 +1,24 @@
+# Introduction
+PyMPDATA examples are bundled with PyMPDATA and located in the examples subfolder.
+They constitute a separate PyMPDATA_examples Python package which is also available at PyPI.
+The examples have additional dependencies listed in PyMPDATA_examples package setup.py file.
+Running the examples requires the PyMPDATA_examples package to be installed.
+
+Below is an example of how to use the PyMPDATA_examples package to run a simple advection-diffusion in 2D
+`PyMPDATA_examples.advection_diffusion_2d`
+![adv_diff](https://github.com/open-atmos/PyMPDATA/releases/download/tip/advection_diffusion.gif)
+
+# Installation
+Since the examples package includes Jupyter notebooks (and their execution requires write access), the suggested install and launch steps are:
+
+```
+git clone https://github.com/open-atmos/PyMPDATA-examples.git
+cd PyMPDATA-examples
+pip install -e .
+jupyter-notebook
+```
+
+Alternatively, one can also install the examples package from pypi.org by using
+```
+pip install PyMPDATA-examples.
+```