Update documentation v2

.gitignore

@@ -134,8 +134,15 @@ data/
 
 uv.lock
 
-# Quarto
+# Docs
+docs/.quarto/
 docs/_site/
-
-# created by quartodoc
-docs/api
+docs/_site_old/
+docs/_freeze/
+docs/api/
+docs/objects.json
+docs/**/*.quarto_ipynb
+docs/examples/*_files/
+docs/examples/getting-started.qmd
+docs/examples/detect-on-dataframes.qmd
+docs/examples/example-water-level.qmd

Makefile

@@ -1,6 +1,6 @@
 LIB = src/tsod
 
-.PHONY: check build lint format test coverage docs clean
+.PHONY: check build lint format test coverage docs convert-notebooks clean
 
 check: lint test
 
@@ -19,7 +19,10 @@ test:
 coverage:
 	uv run pytest --cov-report html --cov=$(LIB) tests/
 
-docs:
+convert-notebooks:
+	uv run python scripts/convert_docs_notebooks.py
+
+docs: convert-notebooks
 	cd docs && uv run quartodoc build
 	uv run quarto render docs
 

docs/_quarto.yml

@@ -2,13 +2,15 @@ project:
   type: website
 
 website:
-  title: "tsod"
+  title: ""
   page-footer: "© 2025 DHI Group"
   repo-url: https://github.com/DHI/tsod
   repo-actions: [edit]
   repo-subdir: docs
+  page-navigation: true
 
   navbar:
+    logo: https://raw.githubusercontent.com/DHI/tsod/main/images/logo/tsod.png
     tools:
     - icon: github
       menu:
@@ -17,13 +19,28 @@ website:
       - text: Report a Bug
         url:  https://github.com/DHI/tsod/issues
     left:
-      - href: index.qmd
-        text: Home
-      - href: getting-started.qmd
-        text: Getting Started
-      - href: design.qmd
-      - href: api/index.qmd
-        text: API Reference       
+      - text: Home
+        href: index.qmd
+      - text: User Guide
+        href: user-guide/getting-started.qmd
+      - text: Examples
+        href: examples/index.qmd
+      - text: API Reference
+        href: api/index.qmd    
+
+  sidebar:
+    - title: "User Guide"
+      style: docked
+      contents:
+        - user-guide/getting-started.qmd
+        - user-guide/design.qmd
+    - title: "Examples"
+      style: docked
+      contents:
+        - href: examples/index.qmd
+        - href: examples/getting-started.qmd
+        - href: examples/detect-on-dataframes.qmd
+        - href: examples/example-water-level.qmd
 
 filters:
   - interlinks
@@ -63,6 +80,5 @@ quartodoc:
 format:
   html:
     theme: cosmo
-    toc: true
-  ipynb:
+    css: style.css
     toc: true

docs/examples/_metadata.yml

@@ -0,0 +1,6 @@
+page-layout: full
+execute:
+  freeze: auto  # Cache executed outputs; only re-run cells when source changes.
+format:
+  html:
+    fig-responsive: true

docs/examples/docs_config.json

@@ -0,0 +1,19 @@
+{
+  "examples": [
+    {
+      "notebook": "Getting started.ipynb",
+      "title": "Getting started",
+      "description": "Basic anomaly detection using RangeDetector, GradientDetector, and more."
+    },
+    {
+      "notebook": "Detect on DataFrames.ipynb",
+      "title": "Detect on DataFrames",
+      "description": "Apply a detector to all columns of a DataFrame at once."
+    },
+    {
+      "notebook": "Example Water Level.ipynb",
+      "title": "Example Water Level",
+      "description": "Clean a real water level time series using a combined detector."
+    }
+  ]
+}

docs/examples/index.qmd

@@ -0,0 +1,7 @@
+---
+title: "Examples"
+page-layout: article
+listing: 
+    type: default
+    fields: [image, title, description]
+---

docs/index.qmd

@@ -20,26 +20,28 @@ format-links: false
 Install **tsod** with [`pip`](https://pypi.org/project/tsod/) and get up
 and running in minutes
 
-
+[**Getting started**](user-guide/getting-started.qmd)
 
 ## {{< fa brands python >}} **It's just Python**
 
 Use familiar Python workflows to integrate anomaly detection into your models and pipelines
 
+[**API Reference**](api/index.qmd)
 
 :::
 
 ::: {.g-col-6}
 
 ## {{< fa solid ruler >}} **Rule-based detectors**
 
-Choose from detectors like `RangeDetector` and `ConstantValueDetector` to identify anomalies.
+Choose from detectors like `RangeDetector` and `ConstantValueDetector` to identify anomalies. Explore example notebooks in [**Examples**](examples/index.qmd)
 
 
 ## {{< fa scale-balanced >}} **Open Source, MIT**
 
 **tsod** is licensed under MIT and the source code is available on [GitHub](https://github.com/DHI/tsod)
 
+[**Design philosophy**](user-guide/design.qmd)
 
 :::
 

docs/style.css

@@ -0,0 +1,12 @@
+#quarto-content.page-layout-full main.content.column-body > #title-block-header + p {
+  display: none;
+}
+
+#quarto-content.page-layout-full main.content.column-body {
+  max-width: min(1600px, calc(100vw - 4rem));
+}
+
+.cell-output-display img, .quarto-figure img {
+  max-width: 100%;
+  height: auto;
+}

docs/design.qmd → docs/user-guide/design.qmd

@@ -1,41 +1,41 @@
-# Design philosophy
-
-
-## {{< fa brands python >}} Familiar
-
-tsod aims to use a syntax familiar to users of scientific computing libraries such as Pandas & sckit-learn.
-
-## {{< fa download >}} Easy to install
-
-```bash
-$ pip install tsod
-```
-
-
-## {{< fa brands osi >}} Open Source​
-tsod is an open source project licensed under the MIT license.
-The software is provided free of charge with the source code available for inspection and modification.
-
-Contributions are welcome!
-
-## {{< fa comments >}} Easy to collaborate
-By developing tsod on GitHub along with a completely open discussion, we believe that the collaboration between developers and end-users results in a useful library.
-
-## {{< fa list-ol >}} Reproducible
-By providing the historical versions of tsod on PyPI it is possible to reproduce the behaviour of an older existing system, based on an older version.
-
-**Install specific version**
-
-```bash
-pip install tsod==0.2.0
-```
-
-## {{< fa brands github >}} Easy access to new features
-Features are being added all the time, by developers at DHI in offices all around the globe as well as external contributors using tsod in their work.
-These new features are always available from the [main branch on GitHub](https://github.com/DHI/tsod) and thanks to automated testing, it is always possible to verify that the tests passes before downloading a new development version.
-
-**Install development version**
-
-```bash
-$ pip install https://github.com/DHI/tsod/archive/main.zip
+# Design philosophy
+
+
+## {{< fa brands python >}} Familiar
+
+tsod aims to use a syntax familiar to users of scientific computing libraries such as Pandas & sckit-learn.
+
+## {{< fa download >}} Easy to install
+
+```bash
+$ pip install tsod
+```
+
+
+## {{< fa brands osi >}} Open Source​
+tsod is an open source project licensed under the MIT license.
+The software is provided free of charge with the source code available for inspection and modification.
+
+Contributions are welcome!
+
+## {{< fa comments >}} Easy to collaborate
+By developing tsod on GitHub along with a completely open discussion, we believe that the collaboration between developers and end-users results in a useful library.
+
+## {{< fa list-ol >}} Reproducible
+By providing the historical versions of tsod on PyPI it is possible to reproduce the behaviour of an older existing system, based on an older version.
+
+**Install specific version**
+
+```bash
+pip install tsod==0.2.0
+```
+
+## {{< fa brands github >}} Easy access to new features
+Features are being added all the time, by developers at DHI in offices all around the globe as well as external contributors using tsod in their work.
+These new features are always available from the [main branch on GitHub](https://github.com/DHI/tsod) and thanks to automated testing, it is always possible to verify that the tests passes before downloading a new development version.
+
+**Install development version**
+
+```bash
+$ pip install https://github.com/DHI/tsod/archive/main.zip
 ```