Move docs from readme to markdown files and docstring (#459)

Co-authored-by: Sylwester Arabas <sylwester.arabas@agh.edu.pl>
open-atmos · Sep 30, 2024 · 2e43989 · 2e43989
1 parent 52b1d08
commit 2e43989
Show file tree

Hide file tree

Showing 9 changed files with 708 additions and 547 deletions.
diff --git a/.github/workflows/tests+pypi.yml b/.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:

diff --git a/.pre-commit-config.yaml b/.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

diff --git a/PyMPDATA/__init__.py b/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

diff --git a/README.md b/README.md
diff --git a/docs/markdown/pympdata_examples_landing.md b/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.
+```