diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..c5811f9 --- /dev/null +++ b/.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}` + }); + 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/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/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 77a249e..8b843b6 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 = "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 73987b4..8364576 100644 --- a/pyproject.toml +++ b/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", diff --git a/requirements-docs.txt b/requirements-docs.txt index 910559d..76dd25e 100644 --- a/requirements-docs.txt +++ b/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