From fd96e6d6884edd5e0a5a85e1daefeb2da5d921b2 Mon Sep 17 00:00:00 2001
From: Philip Hartout <philip.hartout@protonmail.com>
Date: Fri, 19 Sep 2025 10:25:12 +0200
Subject: [PATCH 1/3] try out pydata theme

---
 .github/workflows/docs.yml           | 52 ++++++++++++++++++++++++++++
 docs/api_reference/datasets/index.md |  8 +++++
 docs/api_reference/index.md          | 13 ++++---
 docs/api_reference/utils/index.md    |  7 ++++
 docs/conf.py                         | 48 +++++++++++++++++++++++++
 docs/datasets/index.md               | 10 ++++--
 docs/index.md                        | 17 +++++++++
 docs/utils/index.md                  | 10 ++++++
 pixi.toml                            |  4 ++-
 pyproject.toml                       |  9 ++++-
 requirements-docs.txt                |  6 ++++
 11 files changed, 175 insertions(+), 9 deletions(-)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 docs/conf.py
 create mode 100644 docs/utils/index.md

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..066f832
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,52 @@
+name: Deploy Sphinx docs to GitHub Pages
+
+on:
+  push:
+    branches: [ main, master, docs/pydata ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Build Sphinx site
+        run: sphinx-build -b html docs docs/_site
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
diff --git a/docs/api_reference/datasets/index.md b/docs/api_reference/datasets/index.md
index e69de29..3341a4d 100644
--- a/docs/api_reference/datasets/index.md
+++ b/docs/api_reference/datasets/index.md
@@ -0,0 +1,8 @@
+```{toctree}
+:maxdepth: 1
+
+dataset_base_classes
+graph_serialization
+networkx_view
+```
+
diff --git a/docs/api_reference/index.md b/docs/api_reference/index.md
index b804bae..8a7c041 100644
--- a/docs/api_reference/index.md
+++ b/docs/api_reference/index.md
@@ -2,8 +2,13 @@
 
 This section provides detailed documentation for all public APIs in the polygraph package.
 
-## Main Modules
+```{toctree}
+:maxdepth: 2
 
-- **[Metrics](metrics/index.md)** - MMD metrics and evaluation functions for graph analysis
-- **[Datasets](datasets.md)** - Dataset abstractions and graph storage utilities
-- **[Utils](utils/index.md)** - Utility functions including graph descriptors, kernels, and MMD utilities
+datasets/index
+metrics/mmd
+metrics/frechet
+metrics/polygraphscore
+metrics/interface
+utils/index
+```
diff --git a/docs/api_reference/utils/index.md b/docs/api_reference/utils/index.md
index e69de29..72938e9 100644
--- a/docs/api_reference/utils/index.md
+++ b/docs/api_reference/utils/index.md
@@ -0,0 +1,7 @@
+```{toctree}
+:maxdepth: 1
+
+graph_descriptors
+graph_kernels
+```
+
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..675f064
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,48 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+
+project = "PolyGraph"
+copyright = "2025, PolyGraph"
+author = "PolyGraph contributors"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",
+]
+
+autosummary_generate = True
+autodoc_typehints = "description"
+
+templates_path = ["_templates"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+]
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+]
+myst_heading_anchors = 3
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+html_theme = "pydata_sphinx_theme"
+
+html_theme_options = {
+    "show_prev_next": False,
+}
+
+html_static_path = ["_static"]
+
diff --git a/docs/datasets/index.md b/docs/datasets/index.md
index ffb4958..80f1030 100644
--- a/docs/datasets/index.md
+++ b/docs/datasets/index.md
@@ -2,6 +2,10 @@
 
 We provide a variety of benchmark datasets:
 
-- [Synthetic Datasets](small_synthetic.md) - Small datasets of synthetic graphs
-- [Procedural Datasets](procedural.md) - Similar to the synthetic graphs above, but procedurally generated. Datasets may be chosen to be larger.
-- [Real-World Datasets](real_world_topologies.md) - Graphs found in the real world
+```{toctree}
+:maxdepth: 2
+
+small_synthetic
+procedural
+real_world_topologies
+```
diff --git a/docs/index.md b/docs/index.md
index 5192a32..71acabd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -32,3 +32,20 @@ We provide a few basic tutorials:
 - [Basic Usage](tutorials/basic_usage.md) - How to load datasets and compute metrics
 - [Metrics Overview](tutorials/metrics_overview.md) - An overview of which metrics are implemented in `polygraph` (MMD, PGS, VUN, Frechet Distance)
 - [Custom Datasets](tutorials/custom_datasets.md) - How to build custom datasets and share them
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+installation
+tutorials/basic_usage
+tutorials/metrics_overview
+tutorials/custom_datasets
+datasets/index
+metrics/gaussian_tv_mmd
+metrics/pgs5
+metrics/rbf_mmd
+metrics/vun
+utils/index
+api_reference/index
+```
diff --git a/docs/utils/index.md b/docs/utils/index.md
new file mode 100644
index 0000000..5381cec
--- /dev/null
+++ b/docs/utils/index.md
@@ -0,0 +1,10 @@
+# Utilities
+
+```{toctree}
+:maxdepth: 1
+
+descriptors
+kernels
+mmd_utils
+```
+
diff --git a/pixi.toml b/pixi.toml
index 77a249e..9bc3f8c 100644
--- a/pixi.toml
+++ b/pixi.toml
@@ -12,4 +12,6 @@ polygraph = { path = ".", editable = true, extras = ["dev"] }
 
 [tasks]
 test = "pytest -n auto -sv --skip-slow ./tests"
-docs = "mkdocs build"
\ No newline at end of file
+docs = "mkdocs build"
+docs-sphinx = "sphinx-build -b html docs docs/_build/html"
+docs-serve = "sphinx-autobuild --watch polygraph --watch docs -b html docs docs/_build/html --open-browser --port 8000"
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index 73987b4..a3152b2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,7 +55,14 @@ dev = [
     "jinja2",
     "seaborn",
     "tueplots",
-    "typer"
+    "typer",
+    "sphinx",
+    "myst-parser",
+    "pydata-sphinx-theme",
+    "sphinx-copybutton",
+    "sphinx-design",
+    "sphinx-autodoc-typehints",
+    "sphinx-autobuild"
 ]
 gpu = [
     "dgl @ https://data.dgl.ai/wheels/torch-2.4/cu124/dgl-2.4.0%2Bcu124-cp311-cp311-manylinux1_x86_64.whl",
diff --git a/requirements-docs.txt b/requirements-docs.txt
index 910559d..3a20cee 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -3,3 +3,9 @@ mkdocs-material
 mkdocstrings
 mkdocstrings-python
 mkdocs-terminal
+sphinx
+pydata-sphinx-theme
+myst-parser
+sphinx-copybutton
+sphinx-design
+sphinx-autodoc-typehints

From 23cf57aacdf908f70e86714505b46cdae40e6e4a Mon Sep 17 00:00:00 2001
From: Philip Hartout <philip.hartout@protonmail.com>
Date: Fri, 19 Sep 2025 11:00:49 +0200
Subject: [PATCH 2/3] remove mkdocs

---
 .github/workflows/mkdocs.yaml |  6 +---
 mkdocs.yml                    | 60 -----------------------------------
 pixi.toml                     |  2 +-
 pyproject.toml                |  5 ---
 requirements-docs.txt         |  5 ---
 5 files changed, 2 insertions(+), 76 deletions(-)
 delete mode 100644 mkdocs.yml

diff --git a/.github/workflows/mkdocs.yaml b/.github/workflows/mkdocs.yaml
index a47e2a4..c2a8428 100644
--- a/.github/workflows/mkdocs.yaml
+++ b/.github/workflows/mkdocs.yaml
@@ -1,11 +1,7 @@
 name: MkDocs Documentation
 
 on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-  push:
-    branches:
-      - master
+  workflow_dispatch:
 
 jobs:
   deploy-preview:
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index 811b8df..0000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,60 +0,0 @@
-site_name: polygraph
-theme:
-  name: readthedocs  # Optional, but makes docs look better
-  features:
-    - navigation.expand  # Expands all sections by default
-    - navigation.side.indexes
-
-nav:
-  - index.md
-  - Installation: installation.md
-  - Tutorials:
-    - Basic Usage: tutorials/basic_usage.md
-    - Metrics Overview: tutorials/metrics_overview.md
-    - Custom Datasets: tutorials/custom_datasets.md
-  - Base API Reference:
-    - polygraph.metrics:
-      - Interface: api_reference/metrics/interface.md
-      - MMD: api_reference/metrics/mmd.md
-      - PolyGraphScore: api_reference/metrics/polygraphscore.md
-      - Frechet: api_reference/metrics/frechet.md
-    - polygraph.datasets:
-      - Dataset Base Classes: api_reference/datasets/dataset_base_classes.md
-      - NetworkX View: api_reference/datasets/networkx_view.md
-      - Graph Serialization: api_reference/datasets/graph_serialization.md
-    - polygraph.utils:
-      - Graph Descriptors: api_reference/utils/graph_descriptors.md
-      - Graph Kernels: api_reference/utils/graph_kernels.md
-  - Standardized Metrics:
-    - PGS5: metrics/pgs5.md
-    - Gaussian TV MMD: metrics/gaussian_tv_mmd.md
-    - RBF MMD: metrics/rbf_mmd.md
-    - VUN: metrics/vun.md
-  - Datasets:
-    - Small Synthetic Datasets: datasets/small_synthetic.md
-    - Procedural Datasets: datasets/procedural.md
-    - Real-World Datasets: datasets/real_world_topologies.md
-  - Utils:
-    - Graph Descriptors: utils/descriptors.md
-    - Graph Kernels: utils/kernels.md
-    - MMD Utilities: utils/mmd_utils.md
-
-plugins:
-  - search
-  - mkdocstrings:
-      handlers:
-        python:
-          options:
-            extensions:
-              - scripts/griffe_extension.py:JinjaDocstringExtension
-      paths: [polygraph]
-
-markdown_extensions:
-  - admonition
-  - pymdownx.arithmatex:
-      generic: true
-
-
-extra_javascript:
-  - javascript/mathjax.js
-  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
diff --git a/pixi.toml b/pixi.toml
index 9bc3f8c..8b843b6 100644
--- a/pixi.toml
+++ b/pixi.toml
@@ -12,6 +12,6 @@ polygraph = { path = ".", editable = true, extras = ["dev"] }
 
 [tasks]
 test = "pytest -n auto -sv --skip-slow ./tests"
-docs = "mkdocs build"
+docs = "sphinx-build -b html docs docs/_build/html"
 docs-sphinx = "sphinx-build -b html docs docs/_build/html"
 docs-serve = "sphinx-autobuild --watch polygraph --watch docs -b html docs docs/_build/html --open-browser --port 8000"
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index a3152b2..8364576 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -46,11 +46,6 @@ dev = [
     "ipykernel",
     "grakel",
     "pytest-profiling",
-    "mkdocs",
-    "mkdocstrings",
-    "mkdocs-material",
-    "mkdocstrings-python",
-    "mkdocs-terminal",
     "tabulate",
     "jinja2",
     "seaborn",
diff --git a/requirements-docs.txt b/requirements-docs.txt
index 3a20cee..76dd25e 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -1,8 +1,3 @@
-mkdocs
-mkdocs-material
-mkdocstrings
-mkdocstrings-python
-mkdocs-terminal
 sphinx
 pydata-sphinx-theme
 myst-parser

From 28fe054a504b612b3ce1d2e76b61913fa3ba0ca4 Mon Sep 17 00:00:00 2001
From: Philip Hartout <philip.hartout@protonmail.com>
Date: Fri, 19 Sep 2025 11:26:23 +0200
Subject: [PATCH 3/3] update preview docs

---
 .github/workflows/docs.yml | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 066f832..c5811f9 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -3,15 +3,18 @@ name: Deploy Sphinx docs to GitHub Pages
 on:
   push:
     branches: [ main, master, docs/pydata ]
+  pull_request:
+    types: [opened, synchronize, reopened]
   workflow_dispatch:
 
 permissions:
   contents: read
   pages: write
   id-token: write
+  pull-requests: write
 
 concurrency:
-  group: pages
+  group: pages-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -50,3 +53,18 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v4
 
+      - name: Comment PR with preview URL
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const previewUrl = `${{ toJSON(steps.deployment.outputs.page_url) }}`;
+            const issue_number = context.payload.pull_request.number;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              body: `🔍 Documentation preview for this PR: ${previewUrl}`
+            });
+