documentation beef up (incl. example gallery and badge generation) (#…

…1407)

Co-authored-by: Sylwester Arabas <sylwester.arabas@agh.edu.pl>

.github/workflows/readme_snippets.yml

@@ -27,7 +27,7 @@ jobs:
       - run: python -m pip install $PIP_INSTALL_ARGS pytest-codeblocks pytest
       - run: python -m pip install $PIP_INSTALL_ARGS "pyparsing<3.0.0"  # https://github.com/matplotlib/matplotlib/issues/25204
       - run: |
-          python -c "import os,pytest_codeblocks; code=pytest_codeblocks.extract_from_file('README.md'); f=open('readme.py', 'w', encoding='utf-8'); f.write('# coding: utf-8'+os.linesep); f.writelines(block.code for block in code if block.syntax=='Python'); f.close()"
+          python -c "import os,pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pysdm_landing.md'); f=open('readme.py', 'w', encoding='utf-8'); f.write('# coding: utf-8'+os.linesep); f.writelines(block.code for block in code if block.syntax=='Python'); f.close()"
       - run: cat -n readme.py
       - run: |
           python -We readme.py
@@ -51,7 +51,7 @@ jobs:
           python-version: "3.10"
       - run: pip install -e .
       - run: pip install pytest-codeblocks pytest
-      - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('README.md'); f=open('readme.jl', 'w'); f.writelines(block.code for block in code if block.syntax=='Julia'); f.close()"
+      - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pysdm_landing.md'); f=open('readme.jl', 'w'); f.writelines(block.code for block in code if block.syntax=='Julia'); f.close()"
       - uses: julia-actions/setup-julia@v1.9.6
       - run: cat -n readme.jl
       - run: julia readme.jl
@@ -67,7 +67,7 @@ jobs:
           python-version: 3.8
       - run: pip install -e .
       - run: pip install pytest-codeblocks pytest
-      - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('README.md'); f=open('readme.m', 'w'); f.writelines(block.code for block in code if block.syntax=='Matlab'); f.close()"
+      - run: python -c "import pytest_codeblocks; code=pytest_codeblocks.extract_from_file('docs/markdown/pysdm_landing.md'); f=open('readme.m', 'w'); f.writelines(block.code for block in code if block.syntax=='Matlab'); f.close()"
       - run: cat -n readme.m
       - uses: matlab-actions/setup-matlab@v2.1.0
         with:

.github/workflows/tests+artifacts+pypi.yml

@@ -69,10 +69,18 @@ jobs:
         with:
           python-version: 3.9
       - run: |
-          pip install pdoc
+          pip install pdoc nbformat
           pip install -e .
           pip install -e examples
-          PDOC_ALLOW_EXEC=1 python -We -m pdoc -o html PySDM examples/PySDM_examples -t pdoc_templates
+          
+          python - <<EOF
+          import glob, nbformat
+          for notebook_path in glob.glob('examples/PySDM_examples/*/*.ipynb'):
+            with open(notebook_path, encoding="utf8") as fin:
+              with open(notebook_path + ".badges.md", 'w') as fout:
+                fout.write(nbformat.read(fin, nbformat.NO_CONVERT).cells[0].source)
+          EOF
+          PDOC_ALLOW_EXEC=1 python -We -m pdoc -o html PySDM examples/PySDM_examples -t docs/templates --math --mermaid
       - if: ${{ github.ref == 'refs/heads/main' && matrix.platform == 'ubuntu-latest' }}
         uses: JamesIves/github-pages-deploy-action@4.1.1
         with:

.zenodo.json

@@ -58,6 +58,11 @@
       "name": "Mackay, J. Ben",
       "orcid": "0000-0001-8677-3562"
     },
+    {
+      "affiliation": "AGH University of Krakow, Poland",
+      "name": "Magnuszewski, Paweł",
+      "orcid": "0009-0007-9269-6795"
+    },
     {
       "affiliation": "California Institute of Technology, Pasadena, CA, USA",
       "name": "Mints, Mikhail"

PySDM/__init__.py

@@ -1,25 +1,6 @@
 # pylint:disable=invalid-name
 """
-PySDM offers a set of building blocks for development of atmospheric cloud
-simulation systems revolving around the particle-based microphysics modelling concept
-and the Super-Droplet Method algorithm ([Shima et al. 2009](https://doi.org/10.1002/qj.441))
-for numerically tackling the probabilistic representation of particle coagulation.
-
-For an overview of PySDM, see [Bartman, Arabas et al. 2021](https://arxiv.org/abs/2103.17238).
-PySDM is released under the [GNU GPL v3 license](https://www.gnu.org/licenses/gpl-3.0.en.html).
-PySDM development has been spearheaded at the Faculty of Mathematics and Computer Science,
-[Jagiellonian University in Kraków](https://en.uj.edu.pl/en) (the copyright holder).
-
-For details on PySDM dependencies and installation procedures, see project
-[README.md file](https://github.com/open-atmos/PySDM/blob/master/README.md)
-which also includes basic usage examples in **Python**, **Julia** and **Matlab**.
-
-A set of more elaborate examples engineered in Python and accompanied by Jupyter
-notebooks are maintained in the
-[PySDM-examples package](https://github.com/open-atmos/PySDM-examples).
-
-PySDM test-suite built using [pytest](https://docs.pytest.org/) is located in the
-[tests package](https://github.com/open-atmos/PySDM/tree/master/tests).
+.. include:: ../docs/markdown/pysdm_landing.md
 """
 
 from importlib.metadata import PackageNotFoundError, version