Eelbrain · christianbrodbeck · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -18,12 +18,12 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: Cache pip dependencies
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt', '**/pyproject.toml') }}
@@ -51,6 +51,12 @@ jobs:
         # Test that the package can be imported after installation
         python -c "from liveneuro import LiveNeuro, create_sample_brain_data; print('Package imports successful!')"
 
+    - name: Cache MNE datasets
+      uses: actions/cache@v4
+      with:
+        path: ~/mne_data
+        key: mne-data
+
     - name: Run fast tests (Linux)
       if: runner.os == 'Linux'
       run: |
@@ -66,7 +72,7 @@ jobs:
 
     - name: Upload coverage reports to Codecov
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.10'
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         file: ./coverage.xml
         flags: unittests
@@ -81,7 +87,7 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.10"
 

diff --git a/docs/README.rst b/docs/README.rst
@@ -30,7 +30,7 @@ Read the Docs
 -------------
 
 The documentation is automatically built and hosted on Read the Docs at:
-https://liveneuron.readthedocs.io
+https://liveneuro.readthedocs.io
 
 The build is triggered automatically on every push to the main branch.
 

diff --git a/docs/api_reference.rst b/docs/api_reference.rst
@@ -1,7 +1,8 @@
 API Reference
 =============
 
-This page contains the complete API reference for LiveNeuro.
+This page documents the public LiveNeuro API. For guided examples, start with
+the :doc:`user_guide`.
 
 Main Class
 ----------
@@ -11,51 +12,7 @@ Main Class
    :exclude-members: __init__
    :show-inheritance:
 
-   The main visualization class for interactive 2D brain projections with activity time-course plots.
-
-Sample Data Module
-------------------
-
-.. autofunction:: liveneuro.create_sample_brain_data
-
-Data Format
+Sample Data
 -----------
 
-Input Data Expectations
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Vector Data** (with direction and magnitude):
-
-* Eelbrain NDVar with dimensions: ``([case,] time, source, space)``
-* MNE ``VolVectorSourceEstimate`` with matching ``src`` SourceSpaces object
-* Built-in MNE sample data object returned by ``create_sample_brain_data()``
-
-**Scalar Data** (magnitude only):
-
-* Eelbrain NDVar with dimensions: ``([case,] time, source)``
-* Single value per source at each time point
-* Sample-data object returned by ``create_sample_brain_data(has_vector_data=False)``
-
-**Built-in Sample Data:**
-
-* 1589 sources in volumetric source space
-* 76 time points (-100ms to 400ms)
-* Vector data (3D current dipoles)
-
-Exceptions
-----------
-
-The library may raise the following exceptions:
-
-**ValueError**
-  * Invalid ``display_mode`` string
-  * Invalid ``layout_mode`` (not "vertical" or "horizontal" and not registered in LAYOUTS)
-  * Invalid parameter values
-
-**ImportError**
-  * Missing required dependencies
-  * Eelbrain not installed when using eelbrain-specific features
-
-**RuntimeError**
-  * Data processing errors
-  * Visualization rendering errors
+.. autofunction:: liveneuro.create_sample_brain_data
diff --git a/docs/conf.py b/docs/conf.py
@@ -26,7 +26,6 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
-    "myst_parser",
 ]
 
 autodoc_mock_imports = [
@@ -44,24 +43,28 @@
 ]
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    ".ipynb_checkpoints",
+    "README.rst",
+    "Thumbs.db",
+    ".DS_Store",
+]
 
 # The suffix(es) of source filenames.
 source_suffix = {
     ".rst": "restructuredtext",
-    ".md": "markdown",
 }
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
-html_static_path = ["_static"]
+html_static_path = []
 
 # Theme options
 html_theme_options = {
     "logo_only": False,
-    "display_version": True,
     "prev_next_buttons_location": "bottom",
     "style_external_links": True,
     "collapse_navigation": False,
@@ -99,19 +102,6 @@
     "numpy": ("https://numpy.org/doc/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "plotly": ("https://plotly.com/python-api-reference/", None),
+    "mne": ("https://mne.tools/stable/", None),
+    "eelbrain": ("https://eelbrain.readthedocs.io/en/stable/", None),
 }
-
-# MyST-Parser settings
-myst_enable_extensions = [
-    "colon_fence",
-    "deflist",
-    "dollarmath",
-    "fieldlist",
-    "html_admonition",
-    "html_image",
-    "replacements",
-    "smartquotes",
-    "strikethrough",
-    "substitution",
-    "tasklist",
-]
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,62 +1,41 @@
-Welcome to LiveNeuro's documentation!
-======================================
+.. raw:: html
 
-**LiveNeuro** is an interactive 2D brain visualization library using Plotly and Dash, designed for real-time exploration of neural activity data.
+   <p style="text-align: right;">
+     <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python Version"></a>
+     <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+     <a href="https://liveneuro.readthedocs.io/en/latest/index.html"><img src="https://img.shields.io/badge/docs-ReadTheDocs-blue" alt="Documentation"></a>
+   </p>
+
+LiveNeuro
+=========
 
 .. image:: liveNeuron.png
    :alt: LiveNeuro visualization overview
    :align: center
    :width: 720px
 
-.. image:: https://img.shields.io/badge/python-3.10%2B-blue
-   :target: https://www.python.org/downloads/
-   :alt: Python Version
-
-.. image:: https://img.shields.io/badge/license-MIT-green
-   :target: https://opensource.org/licenses/MIT
-   :alt: License
-
-.. image:: https://img.shields.io/badge/docs-ReadTheDocs-blue
-   :target: https://liveneuron.readthedocs.io/en/latest/index.html
-   :alt: Documentation
-
-Key Features
-------------
-
-* **Interactive 2D brain projections** - axial, sagittal, coronal, and hemisphere views
-* **Activity time-course plots** for time series visualization
-* **Optimized arrow rendering** for smoother interaction with dense vector fields
-* **Real-time controls** for time navigation and interaction
-* **Jupyter notebook support** for interactive development
-* **Customizable colormaps** and visualization options
-* **Export capabilities** for static images
-
-Quick Start
------------
-
-Installation
-^^^^^^^^^^^^
-
-**Install from GitHub**
-
-.. code-block:: bash
-
-   pip install https://github.com/liang-bo96/LiveNeuro/archive/refs/heads/main.zip
-
-Basic Usage
-^^^^^^^^^^^
+**LiveNeuro** helps MNE-Python and Eelbrain users inspect volume source estimates
+as interactive 2D brain projections with linked time-course plots.
+It is built on Plotly and Dash, works in notebooks or a browser,
+and accepts MNE volume vector source estimates and :class:`eelbrain.NDVar` objects.
 
-.. code-block:: python
+Start Here
+----------
 
-   from liveneuro import LiveNeuro
+* :ref:`installation`: create an environment and install LiveNeuro.
+* :ref:`quick-start`: open the built-in sample visualization.
+* :ref:`eelbrain-data-input`: plot an :class:`eelbrain.NDVar`.
+* :ref:`mne-data-input`: plot an :class:`mne.VolVectorSourceEstimate`.
+* :doc:`api_reference`: look up constructor parameters and public methods.
 
-   # Create visualization with built-in MNE sample data
-   viz = LiveNeuro()
-
-   # Launch in interactive plot
-   viz.run()
+Highlights
+----------
 
-For a full walkthrough of layouts and controls, start with the :doc:`user_guide`.
+* Linked activity time course with click-to-navigate updates.
+* Interactive sagittal, coronal, axial, and hemisphere projections.
+* Vector-field arrows with scale and threshold controls.
+* Notebook, JupyterLab, and external browser display modes.
+* Static export for figures and presentations.
 
 .. toctree::
    :maxdepth: 2
@@ -67,7 +46,7 @@ For a full walkthrough of layouts and controls, start with the :doc:`user_guide`
    api_reference
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,65 +1,75 @@
+.. _installation:
+
 Installation
 ============
 
-Requirements
-------------
+LiveNeuro requires Python 3.10 or higher and the scientific Python stack used by
+MNE-Python and Eelbrain. For the most reliable setup, create an environment with
+``mamba`` or ``conda`` first, then install LiveNeuro with ``pip``.
+
+Create An Environment
+---------------------
+
+Follow the Eelbrain installation guide for platform-specific dependencies:
 
-LiveNeuro requires Python 3.10 or higher and an environment with Eelbrain
-available. The recommended procedure is to create an environment through
-``mamba`` following the official Eelbrain installation guide, then install
-LiveNeuro with ``pip``:
+* `Eelbrain installation guide <https://eelbrain.readthedocs.io/en/stable/installing.html>`_
+
+For an existing conda-style environment, the minimum Eelbrain install is:
+
+.. code-block:: bash
 
-https://eelbrain.readthedocs.io/en/stable/installing.html
+   mamba install -c conda-forge eelbrain
 
-Install from GitHub
--------------------
+Install LiveNeuro
+-----------------
 
-Install directly from GitHub:
+Install the current development version directly from GitHub:
 
 .. code-block:: bash
 
-   pip install https://github.com/liang-bo96/LiveNeuro/archive/refs/heads/main.zip
+   pip install https://github.com/Eelbrain/LiveNeuro/archive/refs/heads/main.zip
 
-Verify Installation
--------------------
+Verify The Install
+------------------
 
-To verify the installation, run:
+Run a short import check:
 
 .. code-block:: python
 
    from liveneuro import LiveNeuro
-   print("LiveNeuro installed successfully!")
-
-Troubleshooting
----------------
 
-Common Issues
-^^^^^^^^^^^^^
+   viz = LiveNeuro()
+   print("LiveNeuro is ready.")
 
-**ImportError: No module named 'liveneuro'**
+Then continue with :ref:`quick-start`.
 
-Make sure you have installed the package correctly. Try:
+.. _installation-troubleshooting:
 
-.. code-block:: bash
+Installation Troubleshooting
+----------------------------
 
-   pip install --upgrade "https://github.com/liang-bo96/LiveNeuro/archive/refs/heads/main.zip"
+``ImportError: No module named 'liveneuro'``
+   Confirm that the environment running Python is the same one where LiveNeuro
+   was installed, then reinstall or upgrade:
 
-**Plotly/Dash version conflicts**
+   .. code-block:: bash
 
-If you encounter version conflicts, try:
+      pip install --upgrade "https://github.com/Eelbrain/LiveNeuro/archive/refs/heads/main.zip"
 
-.. code-block:: bash
+Missing Eelbrain or scientific dependencies
+   Revisit the Eelbrain installation guide, or install Eelbrain from
+   conda-forge:
 
-   pip install --upgrade plotly dash
+   .. code-block:: bash
 
-**Missing dependencies**
+      mamba install -c conda-forge eelbrain
 
-If Eelbrain is missing or not importable, revisit the Eelbrain installation
-guide for platform-specific environment setup.
+Plotly or Dash version conflicts
+   Upgrade the interactive plotting dependencies inside the active environment:
 
-.. code-block:: bash
+   .. code-block:: bash
 
-   mamba install -c conda-forge eelbrain
+      pip install --upgrade plotly dash
 
-For editable installs, test commands, and repository structure, see the
-repository ``README.md``.
+For editable installs, tests, and repository structure, see the repository
+``README.md``.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,7 +2,5 @@
 sphinx>=7.0.0
 sphinx-rtd-theme>=1.3.0
 sphinx-autodoc-typehints>=1.24.0
-myst-parser>=2.0.0
-