diff --git a/docs/markdown/API.md b/docs/markdown/API.md
index 7eaf597..569e746 100644
--- a/docs/markdown/API.md
+++ b/docs/markdown/API.md
@@ -1,34 +1,29 @@
 # API
 
-```{eval-rst}
+The following pages describe the main objects and function of `nuance`
 
-.. currentmodule:: nuance
+## Main modules
 
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: class.rst
+```{toctree}
+:maxdepth: 1
 
-   Star
+core
+ls
+ps
 
 ```
 
+## Other
+
 ```{eval-rst}
 
 .. currentmodule:: nuance
 
-.. automodule:: nuance.linear_search
-   :members:
-   :show-inheritance:
-
-
-.. automodule:: nuance.periodic_search
-   :members:
-   :show-inheritance:
-
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: class.rst
 
-.. automodule:: nuance.core
-   :members:
-   :show-inheritance:
+   Star
 
 ```
\ No newline at end of file
diff --git a/docs/markdown/core.md b/docs/markdown/core.md
new file mode 100644
index 0000000..5ae2190
--- /dev/null
+++ b/docs/markdown/core.md
@@ -0,0 +1,12 @@
+# core
+
+```{eval-rst} 
+
+
+.. automodule:: nuance.core
+   :members:
+   :show-inheritance:
+
+
+
+```
\ No newline at end of file
diff --git a/docs/markdown/how.md b/docs/markdown/how.md
deleted file mode 100644
index 873d2f1..0000000
--- a/docs/markdown/how.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# How it works
-
-<video width="320" height="240" autoplay loop muted>
-  <source src="notebooks/test.mp4" type="video/mp4">
-</video>
\ No newline at end of file
diff --git a/docs/markdown/ls.md b/docs/markdown/ls.md
new file mode 100644
index 0000000..af5b5fa
--- /dev/null
+++ b/docs/markdown/ls.md
@@ -0,0 +1,10 @@
+# linear search
+
+```{eval-rst} 
+
+.. automodule:: nuance.linear_search
+   :members:
+   :show-inheritance:
+
+
+```
\ No newline at end of file
diff --git a/docs/markdown/ps.md b/docs/markdown/ps.md
new file mode 100644
index 0000000..bc6a2c9
--- /dev/null
+++ b/docs/markdown/ps.md
@@ -0,0 +1,10 @@
+# periodic search
+
+```{eval-rst} 
+
+.. automodule:: nuance.periodic_search
+   :members:
+   :show-inheritance:
+
+
+```
\ No newline at end of file
diff --git a/docs/markdown/tutorials.md b/docs/markdown/tutorials.md
deleted file mode 100644
index a046964..0000000
--- a/docs/markdown/tutorials.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Tutorials
-
-
-```{toctree}
-:maxdepth: 1
-
-lc_prep.ipynb
-gp.ipynb
-multi.ipynb
-```
\ No newline at end of file
diff --git a/nuance/linear_search.py b/nuance/linear_search.py
index e44d290..4270260 100644
--- a/nuance/linear_search.py
+++ b/nuance/linear_search.py
@@ -1,9 +1,14 @@
+"""
+The linear search module provides functions to compute single events statistics.
+"""
+
+from typing import Callable
+
 import jax
 import jax.numpy as jnp
 import numpy as np
-from tqdm.auto import tqdm
-from typing import Callable
 import tinygp
+from tqdm.auto import tqdm
 
 from nuance import DEVICES_COUNT, core
 
@@ -111,7 +116,7 @@ def function(epochs: np.ndarray, durations: np.ndarray):
 def combine_linear_searches(*linear_searches):
     """Combine the results of multiple linear searches
 
-    *linear_searches : list
+    linear_searches : list
         lists of (log likelihoods, model depths, depths variances)
 
     Returns
diff --git a/nuance/periodic_search.py b/nuance/periodic_search.py
index cb67c1d..39540ba 100644
--- a/nuance/periodic_search.py
+++ b/nuance/periodic_search.py
@@ -1,3 +1,9 @@
+"""
+The periodic search module provides functions to compute the probability of 
+a periodic signal to be present in the data, using quantities computed from single 
+events statistics.
+"""
+
 import multiprocess as mp
 import numpy as np
 from tqdm.auto import tqdm