ergodicio · johnbcoughlin · Jan 21, 2026 · Jan 20, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,55 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main, jack-gh-pages]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yaml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build Sphinx docs
+        run: |
+          uv run --with-requirements docs/requirements.txt make -C docs html
+
+      - name: Copy raw markdown sources for LLM access
+        run: |
+          mkdir -p docs/build/html/raw
+          cp -r docs/source/*.md docs/build/html/raw/ 2>/dev/null || true
+          cp -r docs/source/solvers docs/build/html/raw/
+          cp -r docs/source/usage docs/build/html/raw/
+          # Generate index of all markdown files for LLM discovery
+          cd docs/build/html/raw && find . -name "*.md" | sort > index.txt
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -6,3 +6,12 @@
   Code pointer: `adept/_base_.py: ergoExo#_setup_()`
 - The different `ADEPTModule`s are defined in subdirectories of `adept`, for example `_vlasov1d`, `_lpse2d`, etc.
 - `ADEPTModule`s wrap a `diffrax` differential equation solver. The RHS of the ODE (often a discretized PDE) is typically found in a file named `vector_field.py`, in the class `VectorField`. For example, the Vlasov1D RHS is defined in `adept/_vlasov1d/solvers/vector_field.py`.
+
+## Module Documentation
+
+See the [full documentation](https://ergodicio.github.io/adept/) for detailed solver guides.
+
+Quick links to configuration references:
+- [Vlasov-1D Config](source/solvers/vlasov1d/config.md)
+- [Vlasov-2D Config](source/solvers/vlasov2d/config.md)
+- [LPSE-2D Config](source/solvers/lpse2d/config.md)
diff --git a/docs/RUNNING_A_SIM.md b/docs/RUNNING_A_SIM.md
@@ -8,6 +8,8 @@ uv run run.py --cfg path_to_my_config
 
 ## Module-Specific Configuration Reference
 
-- [Vlasov-1D](vlasov1d.md) - 1D Vlasov-Poisson/Maxwell solver with Fokker-Planck collisions
-- [Vlasov-2D](vlasov2d.md) - 2D2V Vlasov-Maxwell solver
-- [LPSE-2D (Envelope-2D)](lpse2d.md) - 2D laser-plasma envelope solver for TPD/SRS
+- [Vlasov-1D](source/solvers/vlasov1d/config.md) - 1D Vlasov-Poisson/Maxwell solver with Fokker-Planck collisions
+- [Vlasov-2D](source/solvers/vlasov2d/config.md) - 2D2V Vlasov-Maxwell solver
+- [LPSE-2D (Envelope-2D)](source/solvers/lpse2d/config.md) - 2D laser-plasma envelope solver for TPD/SRS
+
+See the [full documentation](https://ergodicio.github.io/adept/) for detailed guides and API reference.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,6 @@
--r ../requirements-cpu.txt
-
 # building the docs
 sphinx > 3.0.0
 sphinx_copybutton
 sphinx-rtd-theme >= 1.0, < 2.0
 sphinx-github-style >= 1.0, <= 1.1
+myst-parser >= 2.0
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -55,6 +55,13 @@
     "sphinx.ext.napoleon",
     "sphinx_copybutton",
     "sphinx_github_style",
+    "myst_parser",
+]
+
+# MyST parser configuration
+myst_enable_extensions = [
+    "dollarmath",  # Enable $...$ and $$...$$ math
+    "colon_fence",  # Enable ::: fenced directives
 ]
 # options for sphinx_github_style
 top_level = "adept"

diff --git a/docs/source/dev_guide.rst → docs/source/dev_guide.md b/docs/source/dev_guide.rst → docs/source/dev_guide.md
@@ -1,18 +1,16 @@
-Developer Guide
----------------
+# Developer Guide
 
-In case you are interested in looking past the forward simulation use case, that is, if you are interested in running a program which is not just
+In case you are interested in looking past the forward simulation use case, that is, if you are interested in running a program which is not just:
 
-.. code-block:: bash
-
-    python3 run.py --cfg config/<mode>/<config>
+```bash
+python3 run.py --cfg config/<mode>/<config>
+```
 
 This runs a forward simulation with the specified input parameters. It calls functions within `utils/runner.py` for this.
-The most important one to understand is the ``_run_`` function. Here is a stripped down pseudo-code version
-
-.. code-block:: python
+The most important one to understand is the `_run_` function. Here is a stripped down pseudo-code version:
 
-    def run(cfg: Dict) -> Tuple[Solution, Dict]:
+```python
+def run(cfg: Dict) -> Tuple[Solution, Dict]:
     """
     This function is the main entry point for running a simulation. It takes a configuration dictionary and returns a
     ``diffrax.Solution`` object and a dictionary of datasets.
@@ -100,10 +98,9 @@ The most important one to understand is the ``_run_`` function. Here is a stripp
 
     # fin
     return result, datasets
+```
 
-
-Here, we are heavily relying on two open-source libraries.
+Here, we are heavily relying on two open-source libraries:
 
 1. **MLFlow** as an experiment manager to log parameters, metrics, and artifacts
-
 2. **Diffrax** to solve the ODEs
diff --git a/docs/source/faq.md b/docs/source/faq.md
@@ -0,0 +1,47 @@
+# FAQ
+
+---
+
+**Q. What is novel about ADEPT?**
+
+ADEPT has the following features that make it a unique tool for plasma physics simulations:
+
+- Automatic Differentiation (AD) Enabled (thanks to JAX)
+- GPU-capable (thanks to XLA)
+- Experiment manager enabled (thanks to MLflow)
+- Pythonic
+
+---
+
+**Q. What does AD do for us?**
+
+AD enables the calculation of derivatives of entire simulations, pieces of it, or anything in between. This can be used for:
+
+- Sensitivity analyses
+- Parameter estimation
+- Parameter optimization
+- Model training
+
+---
+
+**Q. Why use MLflow?**
+
+MLFlow handles all the incredibly rote metadata management that computational scientists have historically either just completely ignored, written in an excel file, used a lab notebook, etc. (You may always be an exception!)
+
+You can store parameters (inputs to the simulation, box size, driver parameters, etc.), metrics (run time, total electrostatic energy, temperature at t=200 ps etc.) and artifacts (the fields, distribution functions, plots, post processed quantities, configuration etc.) in a single place.
+
+This place can either be your local machine, or better yet, a remote server that is backed by a database and an object store.
+
+---
+
+**Q. Why use xarray?**
+
+Xarray is a great way to handle gridded data. It is performant, has a stable API, has high level plotting features. It is fairly portable, maybe not as much as HDF5, but it is a netCDF4 file so it can't be that bad!
+
+---
+
+**Q. Why use diffrax?**
+
+Diffrax provides the ODE integrator capabilities. However, you can, and we often do, side-step the actual time-integrator but only use diffrax for yet again, a stable API that enables us to save data in a consistent way. Diffrax lets us pass functions to the integrator, which is a great way to store custom post-processed (e.g. interpolated) quantities. You can also handle the result in the same consistent way. Yes, we could have just designed an API. But diffrax DOES also provide the time integrator.
+
+Another thing diffrax does is it has a great loop handling system that compiles much faster than anything I have written. I don't know why that is, but it is.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,16 +1,11 @@
-.. adept documentation master file, created by
-   sphinx-quickstart on Wed Nov  8 15:35:24 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 ADEPT
 =========
 
 .. image:: adept-logo.png
    :alt: ADEPT
    :align: right
 
-**ADEPT** is a set of **A** utomatic **D** ifferentation **E** nabled **P** lasma **T** ransport solvers.
+**ADEPT** is a set of **A** utomatic **D** ifferentiation **E** nabled **P** lasma **T** ransport solvers.
 
 
 Examples
@@ -23,30 +18,47 @@ Documentation
 ------------------
 
 .. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
    usage
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Solvers
+
    solvers
+   solvers/vlasov1d/overview
+   solvers/vlasov2d/overview
+   solvers/lpse2d/overview
+   solvers/vfp1d/overview
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Configuration Reference
+
+   solvers/vlasov1d/config
+   solvers/vlasov2d/config
+   solvers/lpse2d/config
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
    faq
    api
-   :maxdepth: 2
-   :caption: Contents:
+   dev_guide
+   tests
 
 .. note::
 
    This project is under active development.
 
 
-Contributing guide
+Contributing Guide
 ------------------------
 The contributing guide is in development but for now, just make an issue / pull request and we can go from there :)
 
 Citation
 ------------
-[1] A. S. Joglekar and A. G. R. Thomas, “Machine learning of hidden variables in multiscale fluid simulation,” Mach. Learn.: Sci. Technol., vol. 4, no. 3, p. 035049, Sep. 2023, doi: 10.1088/2632-2153/acf81a.
-
-
-.. Indices and tables
-.. ==================
-
-.. * :ref:`genindex`
-.. * :ref:`modindex`
-.. * :ref:`search`
+[1] A. S. Joglekar and A. G. R. Thomas, "Machine learning of hidden variables in multiscale fluid simulation," Mach. Learn.: Sci. Technol., vol. 4, no. 3, p. 035049, Sep. 2023, doi: 10.1088/2632-2153/acf81a.
diff --git a/docs/source/solvers.md b/docs/source/solvers.md
@@ -0,0 +1,34 @@
+# Available Solvers
+
+ADEPT provides several solver modules for different plasma physics applications.
+
+## Kinetic Solvers
+
+### [Vlasov-1D](solvers/vlasov1d/overview.md)
+
+1D1V Vlasov-Poisson/Maxwell solver with Fokker-Planck collisions. Ideal for studying electron plasma waves, Landau damping, and wave-particle interactions.
+
+- [Overview & Equations](solvers/vlasov1d/overview.md)
+- [Configuration Reference](solvers/vlasov1d/config.md)
+
+### [Vlasov-2D](solvers/vlasov2d/overview.md)
+
+2D2V Vlasov-Maxwell solver for electromagnetic simulations in two spatial dimensions.
+
+- [Overview & Equations](solvers/vlasov2d/overview.md)
+- [Configuration Reference](solvers/vlasov2d/config.md)
+
+### [VFP-1D](solvers/vfp1d/overview.md)
+
+Vlasov-Fokker-Planck solver for electron transport over collisional time-scales.
+
+- [Overview](solvers/vfp1d/overview.md)
+
+## Envelope Solvers
+
+### [LPSE-2D (Envelope-2D)](solvers/lpse2d/overview.md)
+
+2D laser-plasma envelope solver for modeling laser-plasma instabilities including Two-Plasmon Decay (TPD) and Stimulated Raman Scattering (SRS).
+
+- [Overview & Equations](solvers/lpse2d/overview.md)
+- [Configuration Reference](solvers/lpse2d/config.md)
diff --git a/docs/source/solvers.rst b/docs/source/solvers.rst