Docs: Sphinx → properdocs migration + descending-drive Poisson fix (+ Optuna parallelization)

.github/workflows/docs.yml

@@ -0,0 +1,86 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # NEURON + MPI system libraries: the build imports myogen for the
+      # mkdocstrings API reference (and supports opt-in gallery execution via
+      # MKDOCS_GALLERY_PLOT=true). Same set the old Sphinx docs workflow used.
+      - name: Install NEURON/MPI system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libegl1-mesa-dev libgtk2.0-dev \
+            openmpi-bin openmpi-common libopenmpi-dev \
+            infiniband-diags ibverbs-utils libibverbs-dev \
+            libfabric1 libfabric-dev libpsm2-dev librdmacm-dev
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Sync project + docs/nwb extras
+        run: uv sync --locked --group docs --extra nwb
+
+      - name: Compile NMODL mechanisms
+        run: uv run poe setup_myogen
+
+      - name: Build docs site
+        # Execute the example gallery so figures render inline in the deployed
+        # site (parity with the old Sphinx docs). scripts/build_docs.py wraps
+        # `properdocs build` with bounded retries: NEURON's native runtime state
+        # accumulates across mkdocs-gallery's single-process execution and
+        # eventually segfaults, but each executed example is md5-cached, so
+        # retrying resumes past the crash. The wrapper aborts if a retry makes no
+        # progress and validates gallery completeness before the site can deploy.
+        # (gallery_conf.py additionally forces joblib to n_jobs=1 so no loky
+        # worker processes are spawned mid-build.)
+        env:
+          # Execute the gallery (inline plots) only where the site is actually
+          # deployed — the push to main — plus manual dispatch for pre-merge
+          # testing. On pull requests the gallery is source-only so review builds
+          # stay fast (~10s); the slow executed build (NEURON sims + retries to
+          # survive state-accumulation segfaults) runs once per merge.
+          MKDOCS_GALLERY_PLOT: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch' }}
+        run: uv run --group docs python scripts/build_docs.py
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    # Serialize only the Pages deployment — scoping this to the deploy job (not
+    # the whole workflow) keeps PR "Docs" checks from queueing behind a long
+    # main-branch executed build.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v5

.gitignore

@@ -200,3 +200,8 @@ docs/serve_docs.sh
 
 # Local scratch notes (kept in nexus, not the repo)
 notes/
+
+# mkdocs / properdocs build output
+/site/
+# mkdocs-gallery generated pages
+/docs/auto_examples/

README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1 style="display: flex; align-items: center; justify-content: center; gap: 10px;">
     <span>Welcome to</span>
-    <img src="https://raw.githubusercontent.com/NsquaredLab/MyoGen/main/docs/source/_static/myogen_logo.png" height="100" alt="MyoGen Logo">
+    <img src="https://raw.githubusercontent.com/NsquaredLab/MyoGen/main/docs/images/myogen_logo.png" height="100" alt="MyoGen Logo">
   </h1>
 
   <h2>The modular and extensible simulation toolkit for neurophysiology</h2>
@@ -10,9 +10,9 @@
   [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
   [![Version](https://img.shields.io/badge/version-0.10.1-orange.svg)](https://github.com/NsquaredLab/MyoGen)
 
-  [Installation](https://nsquaredlab.github.io/MyoGen/#installation) •
+  [Installation](https://nsquaredlab.github.io/MyoGen/getting-started/#install) •
   [Documentation](https://nsquaredlab.github.io/MyoGen/) •
-  [Examples](https://nsquaredlab.github.io/MyoGen/examples.html) •
+  [Examples](https://nsquaredlab.github.io/MyoGen/auto_examples/01_basic/) •
   [How to Cite](https://nsquaredlab.github.io/MyoGen/#how-to-cite)
 </div>
 
@@ -161,7 +161,7 @@ uv add cupy-cuda12x
 
 📖 **[Read the full documentation](https://nsquaredlab.github.io/MyoGen/)**
 
-- [User Guide](https://nsquaredlab.github.io/MyoGen/neo_blocks_guide.html) — Working with simulation outputs
+- [User Guide](https://nsquaredlab.github.io/MyoGen/neo-blocks/) — Working with simulation outputs
 - [API Reference](https://nsquaredlab.github.io/MyoGen/api/) — Complete class documentation
 - [Examples](examples/) — Step-by-step tutorials from recruitment to EMG
 

docs/api/currents.md

@@ -0,0 +1,7 @@
+# Currents
+
+::: myogen.utils.currents.create_ramp_current
+::: myogen.utils.currents.create_step_current
+::: myogen.utils.currents.create_sinusoidal_current
+::: myogen.utils.currents.create_sawtooth_current
+::: myogen.utils.currents.create_trapezoid_current

docs/api/index.md

@@ -0,0 +1,8 @@
+# API Reference
+
+- [Top-level (`myogen`)](myogen.md)
+- [Simulator](simulator.md)
+- [Currents](currents.md)
+- [Neuron injection & I/O](io-and-neuron.md)
+- [Plotting](plotting.md)
+- [Types](types.md)

docs/api/io-and-neuron.md

@@ -0,0 +1,17 @@
+# Neuron injection & I/O
+
+## Current injection
+::: myogen.utils.neuron.inject_currents_into_populations.inject_currents_into_populations
+::: myogen.utils.neuron.inject_currents_into_populations.inject_currents_and_simulate_spike_trains
+
+## Persistence
+::: myogen.utils.continuous_saver.ContinuousSaver
+::: myogen.utils.continuous_saver.convert_chunks_to_neo
+
+## NWB export
+!!! note
+    NWB export requires optional dependencies: `pip install myogen[nwb]`.
+
+::: myogen.utils.nwb.export_to_nwb
+::: myogen.utils.nwb.export_simulation_to_nwb
+::: myogen.utils.nwb.validate_nwb

docs/api/myogen.md

@@ -0,0 +1,17 @@
+# Top-level API (`myogen`)
+
+## Reproducibility
+
+Module-level state:
+
+- **`myogen.RANDOM_GENERATOR`** — deprecated compatibility attribute; use `get_random_generator()` instead.
+- **`myogen.SEED`** — deprecated compatibility attribute; use `get_random_seed()` instead.
+
+::: myogen.set_random_seed
+::: myogen.get_random_generator
+::: myogen.get_random_seed
+::: myogen.derive_subseed
+::: myogen.load_nmodl_mechanisms
+::: myogen.get_mechanism_parameters
+::: myogen.validate_mechanism_parameter
+::: myogen.set_mechanism_param

docs/api/plotting.md

@@ -0,0 +1,8 @@
+# Plotting
+
+::: myogen.utils.plotting.plot_raster_spikes
+::: myogen.utils.plotting.plot_membrane_potentials
+::: myogen.utils.plotting.plot_muscle_dynamics
+::: myogen.utils.plotting.plot_antagonist_muscle_comparison
+::: myogen.utils.plotting.plot_spindle_dynamics
+::: myogen.utils.plotting.plot_gto_dynamics

docs/api/simulator.md

@@ -0,0 +1,53 @@
+# Simulator
+
+## Recruitment
+::: myogen.simulator.RecruitmentThresholds
+
+## Neuron populations
+::: myogen.simulator.neuron.populations.AlphaMN__Pool
+::: myogen.simulator.neuron.populations.DescendingDrive__Pool
+
+`DescendingDrive_Gamma__Pool` is a backward-compatibility alias. New code should
+prefer `DescendingDrive__Pool(process_type="gamma", shape=...)`.
+
+::: myogen.simulator.neuron.populations.DescendingDrive_Gamma__Pool
+::: myogen.simulator.neuron.populations.AffIa__Pool
+::: myogen.simulator.neuron.populations.AffII__Pool
+::: myogen.simulator.neuron.populations.AffIb__Pool
+::: myogen.simulator.neuron.populations.GII__Pool
+::: myogen.simulator.neuron.populations.GIb__Pool
+
+## Network & runner
+::: myogen.simulator.Network
+::: myogen.simulator.SimulationRunner
+
+## Muscle & force
+::: myogen.simulator.Muscle
+::: myogen.simulator.HillModel
+::: myogen.simulator.ForceModel
+::: myogen.simulator.ForceModelVectorized
+
+## EMG
+::: myogen.simulator.SurfaceEMG
+::: myogen.simulator.IntramuscularEMG
+::: myogen.simulator.SurfaceElectrodeArray
+::: myogen.simulator.IntramuscularElectrodeArray
+
+## Proprioception
+::: myogen.simulator.SpindleModel
+::: myogen.simulator.GolgiTendonOrganModel
+::: myogen.simulator.JointDynamics
+
+## Geometry & biomechanics
+::: myogen.simulator.MuscleGeometry
+::: myogen.simulator.JointGeometry
+::: myogen.simulator.JointBiomechanics
+
+## Grid / Neo utilities
+::: myogen.simulator.create_grid_signal
+::: myogen.simulator.signal_to_grid
+::: myogen.simulator.get_electrode
+::: myogen.simulator.get_row
+::: myogen.simulator.get_column
+
+The deprecated `GridAnalogSignal` compatibility class is intentionally excluded.