Merge pull request #28 from rohanbabbar04/docs

Add Documentation

.gitignore

@@ -53,3 +53,9 @@ coverage.xml
 # Operating system files
 .DS_Store
 Thumbs.db
+
+# Sphinx documentation
+docs/_build/
+_build
+jupyter_execute
+docs/api/generated

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+   install:
+   - requirements: requirements-docs.txt
+   - method: pip
+     path: .

docs/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = # "-W" treats warnings as errors
+SPHINXBUILD   ?= sphinx-multiversion
+SOURCEDIR     = .
+BUILDDIR      ?= _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+# For local build
+local:
+	sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/autosummary/class.rst

@@ -0,0 +1,11 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+    .. rubric:: Methods
+
+    {% for item in methods if item != "__init__" %}
+    .. automethod:: {{ objname }}.{{ item }}
+    {%- endfor %}

docs/_templates/autosummary/function.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}

docs/api/index.rst

@@ -0,0 +1,14 @@
+API Reference
+=============
+
+This reference provides detailed documentation for user functions in the current release of Simuk.
+
+Simulation based calibration
+----------------------------
+
+.. currentmodule:: simuk
+
+.. autosummary::
+   :toctree: generated/
+
+    SBC

docs/changelog.rst

@@ -0,0 +1,5 @@
+Changelog
+=========
+
+.. include:: ../CHANGELOG.md
+   :parser: myst_parser.sphinx_

docs/conf.py

@@ -0,0 +1,124 @@
+# ruff: noqa
+# -*- coding: utf-8 -*-
+import os
+import sys
+
+from simuk import __version__
+
+sys.path.insert(0, os.path.abspath("../simuk"))
+
+# -- Project information -----------------------------------------------------
+
+project = "Simuk"
+author = "ArviZ contributors"
+copyright = f"2025, {author}"
+
+# The short X.Y version
+version = __version__
+# The full version, including alpha/beta/rc tags
+release = __version__
+
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",
+    "myst_nb",
+    "matplotlib.sphinxext.plot_directive",
+    "sphinx_tabs.tabs",
+    "sphinx_design",
+    "numpydoc",
+    "jupyter_sphinx",
+]
+
+# -- Extension configuration -------------------------------------------------
+nb_execution_mode = "auto"
+nb_execution_excludepatterns = ["*.ipynb"]
+nb_kernel_rgx_aliases = {".*": "python3"}
+myst_enable_extensions = ["colon_fence", "deflist", "dollarmath"]
+autosummary_generate = True
+autodoc_member_order = "bysource"
+numpydoc_show_class_members = False
+numpydoc_show_inherited_class_members = False
+numpydoc_class_members_toctree = False
+
+source_suffix = ".rst"
+
+master_doc = "index"
+language = "en"
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+pygments_style = "sphinx"
+html_css_files = ["custom.css"]
+html_title = "Simuk"
+html_short_title = "Simuk"
+html_theme = "pydata_sphinx_theme"
+
+html_theme_options = {
+    "collapse_navigation": True,
+    "show_toc_level": 2,
+    "navigation_depth": 4,
+    "search_bar_text": "Search the docs...",
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/arviz-devs/simuk",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+    # "logo": {
+    #     "image_light": "Simuk_flat.png",
+    #     "image_dark": "Simuk_flat_white.png",
+    # },
+}
+html_context = {
+    "github_user": "arviz-devs",
+    "github_repo": "simuk",
+    "github_version": "main",
+    "doc_path": "docs/",
+    "default_mode": "light",
+}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+htmlhelp_basename = "simukdoc"
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_documents = [
+    (master_doc, "simuk.tex", "simuk Documentation", "The developers of simuk", "manual"),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+man_pages = [(master_doc, "simuk", "simuk Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+texinfo_documents = [
+    (
+        master_doc,
+        "simuk",
+        "simuk Documentation",
+        author,
+        "simuk",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+epub_exclude_files = ["search.html"]

docs/contributing.rst

@@ -0,0 +1,6 @@
+Contributing
+============
+
+We welcome contributions from interested individuals or groups! For information about contributing to Simuk check out our instructions, policies, and guidelines `here <https://github.com/arviz-devs/simuk/blob/main/CONTRIBUTING.md>`_.
+
+See the `GitHub contributor page <https://github.com/arviz-devs/simuk/graphs/contributors>`_.

docs/examples.rst

@@ -0,0 +1,19 @@
+Examples
+========
+
+The gallery below presents examples that demonstrate the use of Simuk.
+
+.. grid:: 1 2 3 3
+   :gutter: 2 2 3 3
+
+   .. grid-item-card::
+      :link: ./examples/gallery/sbc.html
+      :text-align: center
+      :shadow: none
+      :class-card: example-gallery
+
+      .. image:: examples/img/sbc.png
+         :alt: SBC
+
+      +++
+      SBC

docs/examples/gallery/sbc.md

@@ -0,0 +1,103 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Simulation based calibration
+
+This example demonstrates how to use the `SBC` class for simulation-based calibration, supporting both PyMC and Bambi models.
+
+```{jupyter-execute}
+
+import matplotlib.pyplot as plt
+import numpy as np
+import simuk
+```
+
+::::::{tab-set}
+:class: full-width
+
+:::::{tab-item} PyMC
+:sync: pymc
+
+First, define a PyMC model. In this example, we will use the centered eight schools model.
+
+```{jupyter-execute}
+
+import pymc as pm
+
+data = np.array([28.0, 8.0, -3.0, 7.0, -1.0, 1.0, 18.0, 12.0])
+sigma = np.array([15.0, 10.0, 16.0, 11.0, 9.0, 11.0, 10.0, 18.0])
+
+with pm.Model() as centered_eight:
+    mu = pm.Normal('mu', mu=0, sigma=5)
+    tau = pm.HalfCauchy('tau', beta=5)
+    theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)
+    y_obs = pm.Normal('y', mu=theta, sigma=sigma, observed=data)
+```
+
+Pass the model to the SBC class, set the number of simulations to 100, and run the simulations. This process may take 
+some time since the model runs multiple times.
+
+```{jupyter-execute}
+
+sbc = simuk.SBC(centered_eight,
+    num_simulations=100,
+    sample_kwargs={'draws': 25, 'tune': 50})
+
+sbc.run_simulations()
+```
+
+To compare the prior and posterior distributions, we will plot the results. You can adjust the type of visualization 
+using the ``kind`` parameter. We use the empirical CDF to compare the differences between the prior and posterior.
+
+```{jupyter-execute}
+
+sbc.plot_results(kind="ecdf")
+```
+
+:::::
+
+:::::{tab-item} Bambi
+:sync: bambi
+
+Now, we define a Bambi Model.
+
+```{jupyter-execute}
+
+import bambi as bmb
+import pandas as pd
+
+x = np.random.normal(0, 1, 200)
+y = 2 + np.random.normal(x, 1)
+df = pd.DataFrame({"x": x, "y": y})
+bmb_model = bmb.Model("y ~ x", df)
+```
+
+Pass the model to the `SBC` class, set the number of simulations to 100, and run the simulations. 
+This process may take some time, as the model runs multiple times
+
+```{jupyter-execute}
+
+sbc = simuk.SBC(bmb_model,
+    num_simulations=100,
+    sample_kwargs={'draws': 25, 'tune': 50})
+
+sbc.run_simulations()
+```
+
+To compare the prior and posterior distributions, we will plot the results. You can customize the visualization type 
+using the `kind` parameter. The example below displays a histogram.
+
+```{jupyter-execute}
+
+sbc.plot_results(kind="hist")
+```
+
+:::::