Release 0.7.0

.gitignore

@@ -28,4 +28,8 @@ build
 # linked case studies
 bufferguts
 guts_base
-docs/source/*/case_studies
+docs/source/*/case_studies
+docs/source/examples/lotka_volterra_case_study/*
+!docs/source/examples/lotka_volterra_case_study/index.md
+docs/source/examples/tktd_rna_pulse/*
+!docs/source/examples/tktd_rna_pulse/index.md

.readthedocs.yaml

@@ -14,6 +14,16 @@ build:
     # nodejs: "19"
     # rust: "1.64"
     # golang: "1.19"
+  jobs:
+    pre_build:
+    - bash ./docs/run_doctest.sh
+    - bash ./docs/build_user_guide.sh
+    # examples are too expensive for readthedocs.
+    # Readthedocs community has 15 min build limits. 
+    # examples should be uploaded as pre-built jupyter notebooks 
+    # on github.
+    - bash ./docs/build_examples.sh no-execute
+
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

docs/README.md

@@ -1,5 +1,39 @@
 # Documentation developer documentation
 
+## Building the documentation
+
+The build process of the documentation is containerized in these commands.
+They are used in jobs that extend the build process configured in the `.readthedocs.yml` 
+config file (https://docs.readthedocs.com/platform/stable/build-customization.html) but 
+can also be executed locally with a linux terminal.
+
+```bash
+# run the doctests (pre_build)
+bash ./docs/run_doctest.sh
+
+# build the documentation with sphinx (build)
+bash ./docs/build_documentation.sh
+
+# this is a post_build job
+bash ./docs/build_user_guide.sh
+
+# this is a post_build job
+# can be run with the no-execute argument to disable executing the notebook
+# ATTENTION!! Make sure that the notebooks listed in the index of the docs/examples are matched by the names of the notebooks in the scripts folder of the case study 
+bash ./docs/build_examples.sh
+```
+
+Testing the notebooks is thereby the responsibility of the case study provider.
+
+TODO: What I could do in the future is add a watermark, which version of pymob was used to gernerate the case-study. Or next level, build the examples on push and save as an artifact so they can be downloaded
+
+### Check list
+
+- [ ] If case studies were updated go to the respective branch
+      of the release (e.g. releases/0.5.x) and execute the jupyter notebooks locally with the latest pymob version and upload to the remote repository 
+- [ ] push to the pymob remote to trigger a documentation 
+      build. This will run doctests, execute the user guide pull the examples and convert them to notebooks
+
 
 ## Executing and building examples.
 
@@ -26,6 +60,9 @@ pytest --doctest-modules --disable-warnings \
     --ignore=inference/optimization.py
 cd ..
 ```
+
+This is now implemented in `docs/run_doctests.sh`.
+
 ### Testing inference
 
 + LONG INFERENCE -> CASE STUDY
@@ -66,6 +103,11 @@ jupyter nbconvert --to markdown --execute --output_dir docs/source/examples/CASE
 # repeat last step for 2nd example, ...
 ```
 
+Case studies should be selected carefully. Not any case study should be taken up in the
+examples, because maintaining them with each pymob release (minor version), would become
+increasingly tedious. On the flip side, maintaining case studies and ensuring they are 
+always compatible to the latest pymob release would make experiences with pymob much more
+smooth.
 
 
 These commands should be integrated in pre-release CI pipelines. This is because more sophisticated notebooks, will take quite some time to compile. This is usually unnecessary when making development releases or pre-releases. But when updating the standard release available at `pip install pymob` (e.g. 0.4.1), then the examples in the documentation must be tested.

docs/build_documentation.sh

@@ -0,0 +1,2 @@
+#!/bin/usr/bash
+sphinx-apidoc  -o docs/source/api pymob && sphinx-build -M html docs/source/ docs/build/

docs/build_examples.sh

@@ -0,0 +1,57 @@
+#!/bin/usr/bash
+
+
+EXECUTE_NOTEBOOKS=$1
+
+# Check the value of the environmental variable
+if [ "$EXECUTE_NOTEBOOKS" == "no-execute" ]; then
+    nb_exec=""
+else
+    nb_exec="--execute"
+fi
+
+
+update_repo() {
+  local REPO=$1
+  local DIRECTORY=$2
+  local CWD=$PWD
+
+  if [ ! -d "$CASE_STUDY_DIR/$DIRECTORY" ]; then
+    # clone if it does not exist
+    git clone "$REPO" $CASE_STUDY_DIR/"$DIRECTORY"
+  else
+    # update if it exists
+    cd $CASE_STUDY_DIR/$DIRECTORY
+    git pull
+    cd $CWD
+  fi
+
+  # Check the value of the environmental variable
+  if [ "$EXECUTE_NOTEBOOKS" == "no-execute" ]; then
+      echo "Not installing case study: $DIRECTORY"
+  else
+      echo "Installing case study: $DIRECTORY"
+      pip install "$CASE_STUDY_DIR/$DIRECTORY"
+  fi
+
+}
+
+
+CASE_STUDY_DIR="./docs/source/examples/case_studies"
+
+# lotka volterra
+REPO="https://github.com/flo-schu/lotka_volterra_case_study.git"
+DIRECTORY="lotka_volterra_case_study"
+update_repo $REPO $DIRECTORY
+
+jupyter nbconvert --to markdown ${nb_exec} "$CASE_STUDY_DIR/$DIRECTORY/scripts/hierarchical_model.ipynb" --output-dir="docs/source/examples/$(basename "$DIRECTORY")/"
+jupyter nbconvert --to markdown ${nb_exec} "$CASE_STUDY_DIR/$DIRECTORY/scripts/hierarchical_model_varying_y0.ipynb" --output-dir="docs/source/examples/$(basename "$DIRECTORY")/"
+
+
+# Tktd rna pulse
+REPO="https://github.com/flo-schu/tktd_rna_pulse.git"
+DIRECTORY="tktd_rna_pulse"
+echo "$PWD"
+update_repo $REPO $DIRECTORY
+
+jupyter nbconvert --to markdown ${nb_exec} "$CASE_STUDY_DIR/$DIRECTORY/scripts/tktd_rna_5_*.ipynb" --output-dir="docs/source/examples/$(basename "$DIRECTORY")/"

docs/build_user_guide.sh

@@ -0,0 +1,11 @@
+#!/bin/usr/bash
+
+# gettig started
+jupyter nbconvert --to markdown --execute docs/source/user_guide/superquickstart.ipynb
+
+# user guide
+# quickstaart needs to go before framework overview because generated scenario is needed for the framework overview
+jupyter nbconvert --to markdown --execute docs/source/user_guide/quickstart.ipynb
+jupyter nbconvert --to markdown --execute docs/source/user_guide/Introduction.ipynb
+jupyter nbconvert --to markdown --execute docs/source/user_guide/advanced_tutorial_ODE_system.ipynb
+jupyter nbconvert --to markdown --execute docs/source/user_guide/framework_overview.ipynb

docs/run_doctest.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+cd pymob
+pytest --doctest-modules --disable-warnings \
+    --ignore=inference/interactive.py \
+    --ignore=inference/sbi \
+    --ignore=inference/optimization.py
+
+rm -rf case_studies/testing
+rmdir case_studies
+cd ..

docs/source/conf.py

@@ -15,7 +15,7 @@
 project = "pymob"
 copyright = "2024, Florian Schunck"
 author = "Florian Schunck"
-release = "0.6.3"
+release = "0.6.4"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration