Refactor the entire documentation

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+# From https://github.com/eeholmes/readthedoc-test/blob/main/.github/workflows/docs_pages.yml
+name: docs
+
+# execute this workflow automatically when a we push to main
+on:
+  push:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+
+  build_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v3
+        with:
+          path: master
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v3
+        with:
+          path: gh-pages
+          ref: gh-pages
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          cd ./master
+          python -m pip install .[docs]
+      - name: Make the Sphinx docs
+        run: |
+          cd ./master/docsrc
+          make clean
+          make github
+      - name: Commit changes to docs
+        run: |
+          cd ./gh-pages
+          cp -R ../master/docs/* ./
+          git config --local user.email ""
+          git config --local user.name "github-actions"
+          git add -A
+          if ! git diff-index --quiet HEAD; then
+            git commit -m "auto: Rebuild docs."
+            git  push
+          else
+            echo No commit made because the docs have not changed.
+          fi

.github/workflows/tests.yml

@@ -1,7 +1,8 @@
 name: Tests
 
 on:
-  - push
+  - push:
+      branches: [master]
   - pull_request
 
 jobs:

.gitignore

@@ -4,11 +4,10 @@ __pycache__/
 */__pycache__/
 projects/
 */bayesflow.egg-info
-docs/build/
+docsrc/_build/
 build
+docs/
 
-# Notebooks
-docs/source/tutorial_notebooks/**
 
 # mypy
 .mypy_cache
@@ -31,3 +30,6 @@ docs/source/tutorial_notebooks/**
 
 # tox
 .tox
+
+# MacOS
+.DS_Store

CONTRIBUTING.md → CONTRIBUTING

@@ -1,5 +1,5 @@
 Contributing to BayesFlow
-==========
+=========================
 
 Workflow
 --------
@@ -65,3 +65,26 @@ You can run the all tests locally via:
 Or a specific test via:
 
     pytest -e test_[mytest]
+
+Tutorial Notebooks
+------------------
+
+New tutorial notebooks are always welcome! You can add your tutorial notebook file to `examples/` and add a reference 
+to the list of notebooks in `docsrc/source/examples.rst`. 
+Re-build the documentation (see below) and your notebook will be included.
+
+Documentation
+-------------
+
+The documentation uses [sphinx](https://www.sphinx-doc.org/) and relies on [numpy style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) in classes and functions.
+The overall *structure* of the documentation is manually designed. This also applies to the API documentation. This has two implications for you:
+
+1. If you add to existing submodules, the documentation will update automatically (given that you use proper numpy docstrings).
+2. If you add a new submodule or subpackage, you need to add a file to `docsrc/source/api` and a reference to the new module to the appropriate section of `docsrc/source/api/bayesflow.rst`.
+
+You can re-build the documentation with
+
+    cd docsrc/
+    make clean && make github
+
+The entry point of the rendered documentation will be at `docs/index.html`.

INSTALL.rst

@@ -1,5 +1,5 @@
-Install
-=======
+Full Installation Instructions
+==============================
 
 Requirements
 ------------

README.md

@@ -7,13 +7,13 @@ Welcome to our BayesFlow library for efficient simulation-based Bayesian workflo
 
 For starters, check out some of our walk-through notebooks:
 
-1. [Quickstart amortized posterior estimation](docs/source/tutorial_notebooks/Intro_Amortized_Posterior_Estimation.ipynb)
-2. [Detecting model misspecification in posterior inference](docs/source/tutorial_notebooks/Model_Misspecification.ipynb)
-3. [Principled Bayesian workflow for cognitive models](docs/source/tutorial_notebooks/LCA_Model_Posterior_Estimation.ipynb)
-4. [Posterior estimation for ODEs](docs/source/tutorial_notebooks/Linear_ODE_system.ipynb)
-5. [Posterior estimation for SIR-like models](docs/source/tutorial_notebooks/Covid19_Initial_Posterior_Estimation.ipynb)
-6. [Model comparison for cognitive models](docs/source/tutorial_notebooks/Model_Comparison_MPT.ipynb)
-7. [Hierarchical model comparison for cognitive models](docs/source/tutorial_notebooks/Hierarchical_Model_Comparison_MPT.ipynb)
+1. [Quickstart amortized posterior estimation](examples/Intro_Amortized_Posterior_Estimation.ipynb)
+2. [Detecting model misspecification in posterior inference](examples/Model_Misspecification.ipynb)
+3. [Principled Bayesian workflow for cognitive models](examples/LCA_Model_Posterior_Estimation.ipynb)
+4. [Posterior estimation for ODEs](examples/Linear_ODE_system.ipynb)
+5. [Posterior estimation for SIR-like models](examples/Covid19_Initial_Posterior_Estimation.ipynb)
+6. [Model comparison for cognitive models](examples/Model_Comparison_MPT.ipynb)
+7. [Hierarchical model comparison for cognitive models](examples/Hierarchical_Model_Comparison_MPT.ipynb)
 
 ## Project Documentation
 
@@ -247,7 +247,7 @@ conf_matrix = bf.diagnostics.plot_confusion_matrix(sims["model_indices"], model_
 
 For the vast majority of simulated data sets, the "true" data-generating model is correctly identified. With these diagnostic results backing us up, we can proceed and apply our trained network to empirical data.
 
-BayesFlow is also able to conduct model comparison for hierarchical models. See this [tutorial notebook](docs/source/tutorial_notebooks/Hierarchical_Model_Comparison_MPT.ipynb) for an introduction to the associated workflow.
+BayesFlow is also able to conduct model comparison for hierarchical models. See this [tutorial notebook](examples/Hierarchical_Model_Comparison_MPT.ipynb) for an introduction to the associated workflow.
 
 ### References and Further Reading
 

bayesflow/amortizers.py

@@ -219,7 +219,7 @@ def compute_loss(self, input_dict, **kwargs):
         # Case dynamic latent space - function of summary conditions
         if self.latent_is_dynamic:
             logpdf = self.latent_dist(sum_out).log_prob(z)
-        # Case static latent space
+        # Case _static latent space
         else:
             logpdf = self.latent_dist.log_prob(z)
 
@@ -297,7 +297,7 @@ def sample(self, input_dict, n_samples, to_numpy=True, **kwargs):
         if self.latent_is_dynamic:
             z_samples = self.latent_dist(conditions).sample(n_samples)
             z_samples = tf.transpose(z_samples, (1, 0, 2))
-        # Case static latent - marginal samples from the specified dist
+        # Case _static latent - marginal samples from the specified dist
         else:
             z_samples = self.latent_dist.sample((n_data_sets, n_samples))
 
@@ -382,7 +382,7 @@ def log_posterior(self, input_dict, to_numpy=True, **kwargs):
         # Case dynamic latent - function of conditions
         if self.latent_is_dynamic:
             log_post = self.latent_dist(conditions).log_prob(z) + log_det_J
-        # Case static latent - marginal samples from z
+        # Case _static latent - marginal samples from z
         else:
             log_post = self.latent_dist.log_prob(z) + log_det_J
         self._check_output_sanity(log_post)
@@ -1103,8 +1103,8 @@ def sample(self, input_dict, n_samples, to_numpy=True, **kwargs):
         **kwargs     : dict, optional, default: {}
             Additional keyword arguments passed to the summary network as the amortizers
 
-        Returns:
-        --------
+        Returns
+        -------
         samples_dict : dict
             A dictionary with keys `global_samples` and `local_samples`
             Local samples will hold an array-like of shape (num_replicas, num_samples, num_local)

bayesflow/computational_utilities.py

@@ -59,8 +59,8 @@ def posterior_calibration_error(
     max_quantile     : float in (0, 1), optional, default: 0.995
         The maximum posterior quantile to consider
 
-    Returns:
-    --------
+    Returns
+    -------
     calibration_errors : np.ndarray of shape (num_params, ) or (alpha_resolution, num_params),
         if ``aggregator_fun is None``.
         The aggregated calibration error per marginal posterior.
@@ -248,8 +248,8 @@ def expected_calibration_error(m_true, m_pred, num_bins=10):
         Obtaining well calibrated probabilities using bayesian binning.
         In Proceedings of the AAAI conference on artificial intelligence (Vol. 29, No. 1).
 
-    Important
-    ---------
+    Notes
+    -----
     Make sure that ``m_true`` are **one-hot encoded** classes!
 
     Parameters

bayesflow/coupling_networks.py

@@ -601,8 +601,8 @@ def call(self, target_or_z, condition, inverse=False, **kwargs):
         target          :  tf.Tensor
             If inverse=True: The back-transformed z, shape (batch_size, inp_dim)
 
-        Important
-        ---------
+        Notes
+        -----
         If ``inverse=False``, the return is ``(z, log_det_J)``.\n
         If ``inverse=True``, the return is ``target``
         """

bayesflow/helper_networks.py

@@ -292,24 +292,30 @@ def call(self, inputs):
 class ActNorm(tf.keras.Model):
     """Implements an Activation Normalization (ActNorm) Layer.
     Activation Normalization is learned invertible normalization, using
-    a Scale (s) and Bias (b) vector [1].
-        y = s * x + b (forward)
-        x = (y - b)/s (inverse)
+    a Scale (s) and Bias (b) vector::
 
-    The scale and bias can be data dependent initalized, such that the
-    output has a mean of zero and standard deviation of one [1,2].
+       y = s * x + b (forward)
+       x = (y - b)/s (inverse)
+
+    Notes
+    -----
+
+    The scale and bias can be data dependent initialized, such that the
+    output has a mean of zero and standard deviation of one [1]_[2]_.
     Alternatively, it is initialized with vectors of ones (scale) and
     zeros (bias).
 
-    [1] - Kingma, Diederik P., and Prafulla Dhariwal.
-            "Glow: Generative flow with invertible 1x1 convolutions."
-            arXiv preprint arXiv:1807.03039 (2018).
+    References
+    ----------
+
+    .. [1] Kingma, Diederik P., and Prafulla Dhariwal.
+       "Glow: Generative flow with invertible 1x1 convolutions."
+       arXiv preprint arXiv:1807.03039 (2018).
 
-    [2] - Salimans, Tim, and Durk P. Kingma.
-            "Weight normalization: A simple reparameterization to accelerate
-            training of deep neural networks."
-            Advances in neural information processing systems 29
-            (2016): 901-909.
+    .. [2] Salimans, Tim, and Durk P. Kingma.
+       "Weight normalization: A simple reparameterization to accelerate
+       training of deep neural networks."
+       Advances in neural information processing systems 29 (2016): 901-909.
     """
 
     def __init__(self, latent_dim, act_norm_init, **kwargs):
@@ -353,8 +359,8 @@ def call(self, target, inverse=False):
         target          :  tf.Tensor
             If inverse=True: The inversly transformed targets, shape == target.shape
 
-        Important
-        ---------
+        Notes
+        -----
         If ``inverse=False``, the return is ``(z, log_det_J)``.\n
         If ``inverse=True``, the return is ``target``.
         """

bayesflow/inference_networks.py

@@ -167,8 +167,8 @@ def call(self, targets, condition, inverse=False, **kwargs):
         target          :  tf.Tensor
             If inverse=True: The transformed out, shape (batch_size, ...)
 
-        Important
-        ---------
+        Notes
+        -----
         If ``inverse=False``, the return is ``(z, log_det_J)``.\n
         If ``inverse=True``, the return is ``target``.
         """