docs: add docs

docs/index.md

@@ -0,0 +1,3 @@
+# stateless
+
+Statically typed, purely functional effects for Python.

docs/stateless_api.md

@@ -0,0 +1,23 @@
+::: stateless.Effect
+::: stateless.Depend
+::: stateless.Try
+::: stateless.Success
+
+::: stateless.success
+::: stateless.throw
+::: stateless.throws
+::: stateless.catch
+::: stateless.depend
+::: stateless.memoize
+
+::: stateless.repeat
+::: stateless.retry
+
+::: stateless.parallel
+::: stateless.process
+::: stateless.thread
+
+
+::: stateless.Runtime
+
+::: stateless.Schedule

docs/templates/python/material/method.html

@@ -0,0 +1,60 @@
+{{ log.debug() }}
+{% if config.show_if_no_docstring or method.has_contents %}
+
+  <div class="doc doc-object doc-method">
+  {% with html_id = method.path %}
+
+    {% if not root or config.show_root_heading %}
+
+      {% if root %}
+        {% set show_full_path = config.show_root_full_path %}
+        {% set root_members = True %}
+      {% elif root_members %}
+        {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+        {% set root_members = False %}
+      {% else %}
+        {% set show_full_path = config.show_object_full_path %}
+      {% endif %}
+
+      {% filter heading(heading_level,
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=method.name ~ "()") %}
+
+        {% filter highlight(language="python", inline=True) %}
+          {% if show_full_path %}{{ method.path }}{% else %}{{ method.name }}{% endif %}
+          {% with signature = method.signature %}{% include "signature.html" with context %}{% endwith %}
+        {% endfilter %}
+
+
+
+      {% endfilter %}
+
+    {% else %}
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            id=html_id,
+            toc_label=method.path,
+            hidden=True) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
+    {% endif %}
+
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% with docstring_sections = method.docstring_sections %}
+        {% include "docstring.html" with context %}
+      {% endwith %}
+
+      {% if config.show_source and method.source %}
+        <details class="quote">
+          <summary>Source code in <code>{{ method.relative_file_path }}</code></summary>
+          {{ method.source.code|highlight(language="python", linestart=method.source.line_start, linenums=False) }}
+        </details>
+      {% endif %}
+    </div>
+
+  {% endwith %}
+  </div>
+
+{% endif %}

mkdocs.yml

@@ -0,0 +1,28 @@
+site_name: stateless
+site_description: Purely functional, Statically Typed Python
+site_url: https://suned.github.io/stateless
+repo_name: suned/stateless
+repo_url: https://github.com/suned/stateless
+edit_uri: ''
+nav:
+    - 'API Reference':
+        - 'stateless': stateless_api.md
+theme:
+    name: material
+    palette:
+        primary: blue
+    custom_dir: docs/overrides
+markdown_extensions:
+    - codehilite
+    - admonition
+plugins:
+    - search
+    - mkdocstrings:
+        custom_templates: docs/templates
+        handlers:
+            python:
+              options:
+                show_source: false
+                show_root_heading: true
+        watch:
+            - src/stateless

pyproject.toml

@@ -21,6 +21,10 @@ pre-commit = "^3.5.0"
 ruff = "^0.1.6"
 coverage = "^7.3.2"
 toml = "^0.10.2"
+mkdocs = "^1.5.3"
+mkdocstrings = "^0.24.0"
+mkdocs-material = "^9.4.14"
+mkdocstrings-python = "^1.7.5"
 
 
 [tool.mypy]
@@ -36,7 +40,7 @@ disallow_any_generics = true
 
 [tool.ruff]
 select = ["I", "F", "N", "RUF", "D"]
-ignore = ["D107", "D213", "D203", "D202", "D212"]
+ignore = ["D107", "D213", "D203", "D202", "D212", "D407"]
 
 [tool.ruff.per-file-ignores]
 "tests/**/*" = ["D100", "D101", "D102", "D103", "D104", "D105", "D107"]

src/stateless/__init__.py

@@ -15,6 +15,6 @@
     throws,
 )
 from stateless.functions import repeat, retry
-from stateless.parallel import parallel, process
+from stateless.parallel import parallel, process, thread
 from stateless.runtime import Runtime
 from stateless.schedule import Schedule

src/stateless/effect.py

@@ -33,11 +33,9 @@ def success(result: R) -> Success[R]:
     Create an effect that returns a value.
 
     Args:
-    ----
         result: The value to return.
 
     Returns:
-    -------
         An effect that returns the value.
     """
     yield None  # type: ignore
@@ -49,11 +47,9 @@ def throw(reason: E) -> Try[E, Never]:  # type: ignore
     Create an effect that yields an exception.
 
     Args:
-    ----
         reason: The exception to yield.
 
     Returns:
-    -------
         An effect that yields the exception.
     """
     yield reason
@@ -64,11 +60,9 @@ def catch(f: Callable[P, Effect[A, E, R]]) -> Callable[P, Depend[A, E | R]]:
     Catch exceptions yielded by the effect return by `f`.
 
     Args:
-    ----
         f: The function to catch exceptions from.
 
     Returns:
-    -------
         `f` decorated such that exceptions yielded by the resulting effect are returned.
     """
 
@@ -94,11 +88,9 @@ def depend(ability: Type[A]) -> Depend[A, A]:
     Create an effect that yields an ability and returns the ability sent from the runtime.
 
     Args:
-    ----
         ability: The ability to yield.
 
     Returns:
-    -------
         An effect that yields the ability and returns the ability sent from the runtime.
     """
     a = yield ability
@@ -129,11 +121,9 @@ def throws(  # type: ignore
     Decorate functions returning effects by catching exceptions of a certain type and yields them as an effect.
 
     Args:
-    ----
         *errors: The types of exceptions to catch.
 
     Returns:
-    -------
         A decorator that catches exceptions of a certain type from functions returning effects and yields them as an effect.
     """
 
@@ -212,13 +202,11 @@ def memoize(  # type: ignore
     """Memoize a function that returns an effect.
 
     Args:
-    ----
         f: The function to memoize.
         maxsize: The maximum size of the cache.
         typed: Whether to use typed caching.
 
     Returns:
-    -------
         The memoized function.
     """
     if f is None:

src/stateless/functions.py

@@ -27,11 +27,9 @@ def repeat(
     Repeats the effect until the schedule is exhausted, or an exception is yielded.
 
     Args:
-    ----
         schedule: The schedule to repeat the effect according to.
 
     Returns:
-    -------
         A decorator that repeats the effect according to the schedule.
     """
 
@@ -79,11 +77,9 @@ def retry(
     If the effect never returns a value before the schedule is exhausted, a `RetryError` is yielded containing all the errors.
 
     Args:
-    ----
         schedule: The schedule to retry the effect according to.
 
     Returns:
-    -------
         A decorator that retries the effect according to the schedule.
     """
 

src/stateless/parallel.py

@@ -88,7 +88,6 @@ class Parallel:
     Enables running tasks in parallel using threads and processes.
 
     Args:
-    ----
             thread_pool: The thread pool to use to run tasks in parallel.
             pool: The multiprocessing pool to use to run tasks in parallel. Must be a proxy pool.
     """
@@ -149,7 +148,6 @@ def __getstate__(
         Get the state of the Parallel ability for pickling.
 
         Returns
-        -------
             The state of the Parallel ability.
         """
         if self._thread_pool is None:
@@ -174,7 +172,6 @@ def __setstate__(
         Set the state of the Parallel ability from pickling.
 
         Args:
-        ----
             state: The state of the Parallel ability obtained using __getstate__.
         """
         thread_pool_args, pool = state
@@ -220,12 +217,10 @@ def run_thread_tasks(
         Run tasks in parallel using threads.
 
         Args:
-        ----
             runtime: The runtime to run the tasks in.
             tasks: The tasks to run.
 
         Returns:
-        -------
             The results of the tasks.
         """
         self.thread_pool.__enter__()
@@ -242,12 +237,10 @@ def run_process_tasks(
         Run tasks in parallel using processes.
 
         Args:
-        ----
             runtime: The runtime to run the tasks in.
             tasks: The tasks to run.
 
         Returns:
-        -------
             The results of the tasks.
         """
         payloads: list[bytes] = [cloudpickle.dumps((runtime, task)) for task in tasks]
@@ -264,12 +257,10 @@ def run(
         Run tasks in parallel.
 
         Args:
-        ----
             runtime: The runtime to run the tasks in.
             tasks: The tasks to run.
 
         Returns:
-        -------
             The results of the tasks.
         """
         if self.state == "init":
@@ -362,11 +353,9 @@ def process(  # type: ignore
     Create a task that can be run in parallel using processes.
 
     Args:
-    ----
         f: The function to capture as a task.
 
     Returns:
-    -------
         `f` decorated to return a task.
     """
 
@@ -406,11 +395,9 @@ def thread(  # type: ignore
     Create a task that can be run in parallel using threads.
 
     Args:
-    ----
         f: The function to capture as a task.
 
     Returns:
-    -------
         `f` decorated to return a task.
     """
 
@@ -469,11 +456,9 @@ def parallel(  # type: ignore
     If any of the tasks yield an exception, the exception is yielded.
 
     Args:
-    ----
         tasks: The tasks to run.
 
     Returns:
-    -------
         The results of the tasks.
     """
     runtime: "Runtime[Parallel]" = cast("Runtime[Parallel]", (yield Parallel))

src/stateless/runtime.py

@@ -36,11 +36,9 @@ def use(self, ability: A2) -> "Runtime[A | A2]":
         Enables running effects that require the ability.
 
         Args:
-        ----
             ability: The ability to use.
 
         Returns:
-        -------
             A new runtime with the ability.
         """
         return Runtime((ability, *self.abilities))
@@ -50,11 +48,9 @@ def get_ability(self, ability_type: Type[A]) -> A:
         Get an ability from the runtime.
 
         Args:
-        ----
             ability_type: The type of the ability to get.
 
         Returns:
-        -------
             The ability.
         """
 
@@ -75,12 +71,10 @@ def run(self, effect: Effect[A, E, R], return_errors: bool = False) -> R | E:
         Run an effect.
 
         Args:
-        ----
             effect: The effect to run.
             return_errors: Whether to return errors yielded by the effect.
 
         Returns:
-        -------
             The result of the effect.
         """
         try: