Merge pull request #1 from tomsch420/doc-with-jupyter-book

Doc with jupyter book

.gitignore

@@ -1,8 +1,8 @@
-doc/build
-doc/static
 .idea
 .pytest_cache
 build
 dist
 src/random_events.egg-info
 */__pycache__/
+doc/_build
+doc/_autosummary

.readthedocs.yaml

@@ -12,15 +12,18 @@ build:
     python: "3.9"
   apt_packages:
     - graphviz
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "jupyter-book config sphinx docs/"
 
-# Build documentation in the "docs/" directory with Sphinx
-sphinx:
-  configuration: doc/conf.py
-
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-    - requirements: doc/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+      - sphinx
+
+sphinx:
+  builder: html
+

doc/_config.yml

@@ -0,0 +1,55 @@
+#######################################################################################
+# A default configuration that will be loaded for all jupyter books
+# See the documentation for help and more options: 
+# https://jupyterbook.org/customize/config.html
+
+#######################################################################################
+# Book settings
+title                       : Random Events  # The title of the doc. Will be placed in the left navbar.
+author                      : Tom Schierenbeck  # The author of the doc
+copyright                   : "2024"  # Copyright year to be placed in the footer
+logo                        : Tomato.png  # A path to the doc logo
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: doc.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the doc exists on the web
+repository:
+  url: https://github.com/tomsch420/random_events/  # Online location of your doc
+  path_to_book: doc  # Optional path to your doc, relative to the repository root
+  branch: master  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your doc
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+sphinx:
+  extra_extensions:
+    - sphinx_proof
+    - 'sphinx.ext.autodoc'
+    - 'sphinx.ext.autosummary'
+    - 'autoapi.extension'
+  config:
+    suppress_warnings: ["mystnb.unknown_mime_type"]
+    autosummary_generate: True
+    html_js_files:
+      - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
+    autoapi_dirs: ['../src']
+    autoapi_add_toctree_entry: True
+
+parse:
+  myst_enable_extensions:
+    - amsmath

doc/_toc.yml

@@ -0,0 +1,11 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: quickstart
+- file: conceptual_guide
+- file: technical_guide
+- file: advanced_use
+- file: autoapi/index

doc/advanced_use.md

@@ -0,0 +1,92 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+
+# Advanced Use-case
+
+In this tutorial, we will look at a humorous application of random events. 
+This examples shows that elements from the product algebra can take almost any shape, such as a tomato. 
+First, we import the necessary packages and define two variables.
+
+```{code-cell} ipython3
+:tags: []
+
+import os.path
+from random_events.product_algebra import Event, SimpleEvent
+from random_events.variable import Continuous
+from random_events.interval import *
+from PIL import Image
+import numpy as np
+import plotly.graph_objects as go
+
+x = Continuous("x")
+y = Continuous("y")
+```
+
+Next, let's load the logo of this package.
+
+```{code-cell} ipython3
+:tags: []
+path = os.path.join("Tomato.png")
+image = im=Image.open(path)
+image
+```
+
+We can express this image as an event that can be reasoned about.
+
+```{code-cell} ipython3
+:tags: []
+image = np.array(image.resize((18, 17), Image.NEAREST))
+colors = np.unique(image.reshape((image.shape[0] * image.shape[1], image.shape[2])), axis=0)[1:]
+def indices_to_complex_event(indices: np.array) -> Event:
+    result = Event()
+    for index in indices:
+        event = SimpleEvent({y: closed_open(-index[0] - 1, -index[0]),
+                       x: closed_open(index[1], index[1] + 1)})
+        result.simple_sets.add(event)
+    return result.simplify()
+
+fig = go.Figure()
+
+complex_events = []
+
+for color in colors:
+    pixel_indices = np.transpose(np.nonzero(np.all(image == color, axis=-1)))
+    complex_event = indices_to_complex_event(pixel_indices)
+    complex_events.append(complex_event)
+    traces = complex_event.plot(f"rgb({color[0]},{color[1]},{color[2]})")
+    fig.update_layout(complex_event.plotly_layout())
+    fig.add_traces(traces)
+
+fig.update_layout(title="Random Events Tomato")
+fig.show()
+```
+
+While the shape of a tomato as an event that can be used for probabilistic reasoning serves no particular interest, 
+it showcases that random events can take approximately any shape and not "just" rectangles.
+The entire tomate as measurable space is obtained by union of all the events.
+
+```{code-cell} ipython3
+:tags: []
+
+entire_event = complex_events[0] | complex_events[1] | complex_events[2]
+fig = go.Figure(entire_event.plot(), entire_event.plotly_layout())
+fig.update_layout(title="Random Events Tomato as one Event")
+fig.show()
+```
+
+I hope this bizarre examples aids you in understanding of the product algebra capabilities. 
+Using this event, you can calculate things like the probability of a tomato or the conditional distribution given a tomato.
+