Migrate docs to Sphinx and refresh examples UX

.github/workflows/docs-deploy.yml

@@ -6,7 +6,6 @@ on:
       - main
     paths:
       - "docs/**"
-      - "mkdocs.yml"
       - "pyproject.toml"
       - "sst.config.ts"
       - "package.json"
@@ -66,7 +65,7 @@ jobs:
         run: |
           set -euo pipefail
           python -m pip install --upgrade pip
-          python -m pip install mkdocs mkdocs-material mkdocs-jupyter
+          python -m pip install sphinx pydata-sphinx-theme myst-parser myst-nb sphinx-copybutton sphinx-design linkify-it-py
 
       - name: Install deploy dependencies
         run: |

.github/workflows/docs-doctest.yml

@@ -30,7 +30,7 @@ jobs:
         run: |
           set -euo pipefail
           python -m pip install --upgrade pip
-          python -m pip install mkdocs mkdocs-material mkdocs-jupyter pytest
+          python -m pip install sphinx pydata-sphinx-theme myst-parser myst-nb sphinx-copybutton sphinx-design linkify-it-py pytest
 
       - name: Run docs build doctest
         run: |

.gitignore

@@ -28,6 +28,8 @@ MANIFEST
 
 # built docs
 site/
+jupyter_execute/
+.jupyter_cache/
 
 # Installer logs
 pip-log.txt

README.md

@@ -100,7 +100,7 @@ dipole antennas, horn antennas, and planar microwave circuits.
 ## Building the docs
 
 The documentation site is built with
-[MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
+[PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html).
 A [justfile](https://github.com/casey/just) automates the full pipeline.
 
 ```bash
@@ -118,8 +118,8 @@ just doctest
 
 # Or run each step individually:
 just nbrun      # execute docs example notebooks with papermill
-just nbdocs     # no-op (MkDocs renders .ipynb directly)
-just docs       # build the MkDocs static site
+just nbdocs     # no-op (Sphinx renders .ipynb directly)
+just docs       # build the Sphinx static site (strict mode)
 
 # Serve locally for development
 just serve      # starts a dev server on http://localhost:8080
@@ -136,7 +136,7 @@ Router managed by the private website infrastructure.
 
 ```bash
 npm install
-python -m pip install mkdocs mkdocs-material mkdocs-jupyter
+python -m pip install sphinx pydata-sphinx-theme myst-parser myst-nb sphinx-copybutton sphinx-design linkify-it-py
 ```
 
 2. Set environment variables:

docs/conf.py

@@ -0,0 +1,79 @@
+"""Sphinx configuration for PalaceToolkit documentation."""
+
+from __future__ import annotations
+
+project = "PalaceToolkit"
+author = "EpsilonForge"
+
+extensions = [
+    "myst_nb",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",
+    "sphinx_design",
+]
+
+source_suffix = {
+    ".md": "myst-nb",
+    ".ipynb": "myst-nb",
+}
+
+root_doc = "index"
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "**/.ipynb_checkpoints",
+]
+
+# MyST and notebook behavior
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "substitution",
+    "tasklist",
+]
+
+nb_execution_mode = "off"
+nb_render_markdown_format = "myst"
+suppress_warnings = ["myst.header"]
+
+html_theme = "pydata_sphinx_theme"
+html_title = "PalaceToolkit"
+html_logo = "PalaceToolkit.png"
+html_favicon = "PalaceToolkit.png"
+
+html_theme_options = {
+    "show_nav_level": 2,
+    "navigation_with_keys": True,
+    "logo": {
+        "text": "PalaceToolkit",
+    },
+}
+
+html_static_path = [
+    "stylesheets",
+    "javascripts",
+]
+
+html_css_files = ["interactive.css"]
+html_js_files = [
+    "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js",
+    "mathjax.js",
+]
+
+mathjax3_config = {
+    "tex": {
+        "inlineMath": [["$", "$"], ["\\(", "\\)"]],
+        "displayMath": [["$$", "$$"], ["\\[", "\\]"]],
+        "processEscapes": True,
+        "processEnvironments": True,
+    },
+    "options": {
+        "ignoreHtmlClass": "tex2jax_ignore|mathjax_ignore",
+    },
+}

docs/examples/differential_microstrip_modes.ipynb

@@ -14,7 +14,7 @@
     "tags": []
    },
    "source": [
-    "# Differential Microstrip Modes (2D Cross-Section)\n",
+    "# Differential Microstrip Modes\n",
     "\n",
     "This notebook builds a boxed differential microstrip cross-section (substrate + air + ground plane + two PEC strips), solves eigenmodes, and plots the first fields."
    ]
@@ -491,4 +491,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/examples/index.md

@@ -7,36 +7,176 @@ Palace configuration, simulation, and post-processing.
 
 ## Antennas
 
-| Example | Description |
-|:--------|:------------|
-| [Horn Antenna](horn_antenna.ipynb) | WR-90 rectangular waveguide transition to a horn antenna with waveport boundaries. |
-| [Dipole Antenna Mesh](dipole_antenna_mesh.ipynb) | Half-wave dipole geometry and mesh generation workflow. |
-| [Monopole Antenna](monopole_antenna.ipynb) | Quarter-wave monopole example with meshing and Palace setup. |
-| [L Antenna](l_antenna.ipynb) | Bent-wire L-shaped antenna workflow including geometry and driven simulation setup. |
-| [Patch Antenna](patch_antenna.ipynb) | Rectangular patch antenna model with substrate, feed, and boundary setup. |
-| [Vivaldi Antenna](vivaldi_antenna.ipynb) | Tapered-slot (Vivaldi) antenna geometry and simulation example. |
+<div class="ptk-gallery-grid">
+	<a class="ptk-gallery-link" href="horn_antenna.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Horn Antenna preview">
+			<h3>Horn Antenna</h3>
+			<p>WR-90 rectangular waveguide transition to a horn antenna with waveport boundaries.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="dipole_antenna_mesh.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Dipole Antenna Mesh preview">
+			<h3>Dipole Antenna Mesh</h3>
+			<p>Half-wave dipole geometry and mesh generation workflow.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="monopole_antenna.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Monopole Antenna preview">
+			<h3>Monopole Antenna</h3>
+			<p>Quarter-wave monopole example with meshing and Palace setup.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="l_antenna.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="L Antenna preview">
+			<h3>L Antenna</h3>
+			<p>Bent-wire L-shaped antenna workflow including geometry and driven simulation setup.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="patch_antenna.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Patch Antenna preview">
+			<h3>Patch Antenna</h3>
+			<p>Rectangular patch antenna model with substrate, feed, and boundary setup.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="vivaldi_antenna.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Vivaldi Antenna preview">
+			<h3>Vivaldi Antenna</h3>
+			<p>Tapered-slot (Vivaldi) antenna geometry and simulation example.</p>
+		</article>
+	</a>
+</div>
 
 ## Planar Microwave Circuits
 
-| Example | Description |
-|:--------|:------------|
-| [Coax](coax.ipynb) | Coaxial line baseline example for geometry, mesh, and configuration setup. |
-| [Coax to Waveguide Transition](coax_to_waveguide.ipynb) | Driven coax-to-waveguide transition example including geometry, mesh, and setup. |
-| [Open-ended Stub](open_ended_stub.ipynb) | Open-ended microstrip stub component with geometry and simulation setup. |
-| [Step in Width](step_in_width.ipynb) | Microstrip step-discontinuity example for meshing and EM analysis. |
+<div class="ptk-gallery-grid">
+	<a class="ptk-gallery-link" href="coax.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Coax preview">
+			<h3>Coax</h3>
+			<p>Coaxial line baseline example for geometry, mesh, and configuration setup.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="coax_to_waveguide.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Coax to Waveguide Transition preview">
+			<h3>Coax to Waveguide Transition</h3>
+			<p>Driven coax-to-waveguide transition example including geometry, mesh, and setup.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="open_ended_stub.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Open-ended Stub preview">
+			<h3>Open-ended Stub</h3>
+			<p>Open-ended microstrip stub component with geometry and simulation setup.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="step_in_width.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Step in Width preview">
+			<h3>Step in Width</h3>
+			<p>Microstrip step-discontinuity example for meshing and EM analysis.</p>
+		</article>
+	</a>
+</div>
 
 ## Waveguide Structures
 
-| Example | Description |
-|:--------|:------------|
-| [Waveguide Box](waveguide_box.ipynb) | Closed waveguide cavity/box example including full 3D setup and analysis. |
+<div class="ptk-gallery-grid">
+	<a class="ptk-gallery-link" href="waveguide_box.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Waveguide Box preview">
+			<h3>Waveguide Box</h3>
+			<p>Closed waveguide cavity/box example including full 3D setup and analysis.</p>
+		</article>
+	</a>
+</div>
 
 ## Waveguide Mode Solver
 
-| Example | Description |
-|:--------|:------------|
-| [Hollow Rectangular Waveguide Modes](hollow_waveguide_modes.ipynb) | PEC waveguide eigenmodes compared with analytic TE/TM propagation constants. |
-| [Dielectric Waveguide Modes](dielectric_waveguide_modes.ipynb) | Rectangular dielectric core in cladding with guided-mode classification and field plots. |
-| [Microstrip Modes](microstrip_modes.ipynb) | Boxed 2D microstrip cross-section with PEC strip and outer conductor boundaries for hybrid mode analysis. |
-| [Slotline Modes](slotline_modes.ipynb) | Boxed 2D slotline cross-section with two PEC slot conductors and open outer boundaries. |
-| [Differential Microstrip Modes](differential_microstrip_modes.ipynb) | Boxed 2D differential microstrip with ground plane and two PEC strips for coupled-mode analysis. |
+<div class="ptk-gallery-grid">
+	<a class="ptk-gallery-link" href="hollow_waveguide_modes.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Hollow Rectangular Waveguide Modes preview">
+			<h3>Hollow Rectangular Waveguide Modes</h3>
+			<p>PEC waveguide eigenmodes compared with analytic TE/TM propagation constants.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="dielectric_waveguide_modes.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Dielectric Waveguide Modes preview">
+			<h3>Dielectric Waveguide Modes</h3>
+			<p>Rectangular dielectric core in cladding with guided-mode classification and field plots.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="microstrip_modes.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Microstrip Modes preview">
+			<h3>Microstrip Modes</h3>
+			<p>Boxed 2D microstrip cross-section with PEC strip and outer conductor boundaries for hybrid mode analysis.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="slotline_modes.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Slotline Modes preview">
+			<h3>Slotline Modes</h3>
+			<p>Boxed 2D slotline cross-section with two PEC slot conductors and open outer boundaries.</p>
+		</article>
+	</a>
+	<a class="ptk-gallery-link" href="differential_microstrip_modes.html">
+		<article class="ptk-gallery-card">
+			<img src="../_static/patch.png" alt="Differential Microstrip Modes preview">
+			<h3>Differential Microstrip Modes</h3>
+			<p>Boxed 2D differential microstrip with ground plane and two PEC strips for coupled-mode analysis.</p>
+		</article>
+	</a>
+</div>
+
+```{toctree}
+:caption: Antennas
+:maxdepth: 1
+:hidden:
+
+horn_antenna
+dipole_antenna_mesh
+monopole_antenna
+l_antenna
+patch_antenna
+vivaldi_antenna
+```
+
+```{toctree}
+:caption: Planar Microwave Circuits
+:maxdepth: 1
+:hidden:
+
+coax
+coax_to_waveguide
+open_ended_stub
+step_in_width
+```
+
+```{toctree}
+:caption: Waveguide Structures
+:maxdepth: 1
+:hidden:
+
+waveguide_box
+```
+
+```{toctree}
+:caption: Waveguide Mode Solver
+:maxdepth: 1
+:hidden:
+
+hollow_waveguide_modes
+dielectric_waveguide_modes
+microstrip_modes
+slotline_modes
+differential_microstrip_modes
+```

docs/examples/microstrip_modes.ipynb

@@ -14,7 +14,7 @@
     "tags": []
    },
    "source": [
-    "# Microstrip Modes (2D Cross-Section)\n",
+    "# Microstrip Modes\n",
     "\n",
     "This notebook builds a simple boxed microstrip cross-section (substrate + air + PEC strip conductor), solves eigenmodes with `WaveguideModeSolver`, and plots the first fields."
    ]

docs/examples/slotline_modes.ipynb

@@ -14,7 +14,7 @@
     "tags": []
    },
    "source": [
-    "# Slotline Modes (2D Cross-Section)\n",
+    "# Slotline Modes\n",
     "\n",
     "This notebook builds a boxed slotline cross-section (substrate + air + two PEC slot conductors), solves eigenmodes with `WaveguideModeSolver`, and plots mode fields."
    ]

docs/full-course.md

@@ -37,7 +37,7 @@ design workflows.
 ---
 
 <div style="text-align: center; margin: 2em 0;">
-<a href="https://www.epsilonforge.com/#course" class="md-button md-button--primary" style="font-size: 1.2em; padding: 0.8em 2em;">
+<a href="https://www.epsilonforge.com/#course" class="ptk-cta-button" style="font-size: 1.2em; padding: 0.8em 2em;">
     Get the Full Course →
 </a>
 </div>