try out pydata theme

.github/workflows/docs.yml

@@ -0,0 +1,70 @@
+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-${{ github.ref }}
+  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
+
+      - 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}`
+            });
+

.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:

docs/api_reference/datasets/index.md

@@ -0,0 +1,8 @@
+```{toctree}
+:maxdepth: 1
+
+dataset_base_classes
+graph_serialization
+networkx_view
+```
+

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
+```

docs/api_reference/utils/index.md

@@ -0,0 +1,7 @@
+```{toctree}
+:maxdepth: 1
+
+graph_descriptors
+graph_kernels
+```
+

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"]
+

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
+```

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
+```

docs/utils/index.md

@@ -0,0 +1,10 @@
+# Utilities
+
+```{toctree}
+:maxdepth: 1
+
+descriptors
+kernels
+mmd_utils
+```
+

pixi.toml

@@ -12,4 +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"

pyproject.toml

@@ -46,16 +46,18 @@ dev = [
     "ipykernel",
     "grakel",
     "pytest-profiling",
-    "mkdocs",
-    "mkdocstrings",
-    "mkdocs-material",
-    "mkdocstrings-python",
-    "mkdocs-terminal",
     "tabulate",
     "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",

requirements-docs.txt

@@ -1,5 +1,6 @@
-mkdocs
-mkdocs-material
-mkdocstrings
-mkdocstrings-python
-mkdocs-terminal
+sphinx
+pydata-sphinx-theme
+myst-parser
+sphinx-copybutton
+sphinx-design
+sphinx-autodoc-typehints