Overhaul docs with PyData Sphinx Theme

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+# Workflow for building sphinx documentation remotely
+# and deploying the static HTML to a GitHub Pages site.
+# Note this approach does not require the static HTML
+# files to be stored/pushed/committed to an alternate
+# pages branch or anything like that. It uses GitHub Action artifacts.
+# https://github.com/sphinx-notes/pages
+name: Build and Deploy Sphinx Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - pydata-theme
+  release:
+    types:
+      - published
+  pull_request:
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: sphinx-notes/pages@v3

.gitignore

@@ -67,26 +67,7 @@ instance/
 
 # Sphinx documentation
 docs/generated/
-docs/build/doctrees/
-docs/build/html/_sources/
-docs/build/html/_static/bootstrap-2.3.2/
-docs/build/html/_static/bootswatch-2.3.2/
-docs/build/html/_static/bootswatch-3.3.7/cerulean/
-docs/build/html/_static/bootswatch-3.3.7/cosmo/
-docs/build/html/_static/bootswatch-3.3.7/cyborg/
-docs/build/html/_static/bootswatch-3.3.7/darkly/
-docs/build/html/_static/bootswatch-3.3.7/journal/
-docs/build/html/_static/bootswatch-3.3.7/lumen/
-docs/build/html/_static/bootswatch-3.3.7/paper/
-docs/build/html/_static/bootswatch-3.3.7/readable/
-docs/build/html/_static/bootswatch-3.3.7/sandstone/
-docs/build/html/_static/bootswatch-3.3.7/simplex/
-docs/build/html/_static/bootswatch-3.3.7/slate/
-docs/build/html/_static/bootswatch-3.3.7/solar/
-docs/build/html/_static/bootswatch-3.3.7/spacelab/
-docs/build/html/_static/bootswatch-3.3.7/superhero/
-docs/build/html/_static/bootswatch-3.3.7/united/
-docs/build/html/_static/bootswatch-3.3.7/yeti/
+docs/build/
 
 # PyBuilder
 target/
@@ -108,6 +89,7 @@ celerybeat-schedule
 *.sage.py
 
 # Environments
+.conda/
 .env
 .venv
 env/

README.rst

@@ -20,8 +20,8 @@
 
 ----------------
 
-.. figure::  /docs/pictures/yasa_logo.png
-   :align:   center
+.. figure:: https://raw.githubusercontent.com/raphaelvallat/yasa/refs/tags/v0.6.5/docs/pictures/yasa_logo.png
+   :align: center
 
 **YASA** (*Yet Another Spindle Algorithm*) is a command-line sleep analysis toolbox in Python. The main functions of YASA are:
 
@@ -124,8 +124,8 @@ Gallery
 
 Below some plots demonstrating the functionalities of YASA. To reproduce these, check out the `tutorial (Jupyter notebooks) <https://github.com/raphaelvallat/yasa/tree/master/notebooks>`_.
 
-.. figure::  /docs/pictures/gallery.png
-  :align:   center
+.. figure:: https://raw.githubusercontent.com/raphaelvallat/yasa/refs/tags/v0.6.5/docs/pictures/gallery.png
+  :align: center
 
   *The top plot show an overlay of the detected spindles on real EEG data. The middle left panel shows a time-frequency representation of the whole-night recording (spectrogram), plotted with the hypnogram (sleep stages) on top. The middle right panel shows the sleep stage probability transition matrix, calculated across the entire night. The bottom row shows, from left to right: a topographic plot, the average template of all detected slow-waves across the entire night stratified by channels, and a phase-amplitude coupling comodulogram.*
 

docs/_static/css/custom.css

@@ -0,0 +1,15 @@
+/* -------------------- THEME OVERRIDES -------------------- */
+
+
+/* -------------------- NAV BAR-------------------- */
+
+/* navbar logo needs to be shrunk a bit */
+html .navbar-brand img {
+  height: calc(var(--pst-header-height) / 3);
+  width: auto;
+}
+
+/* navbar logo needs to be inverted for visibility in light theme */
+html[data-theme="light"] .navbar-brand img {
+  filter: invert(1);
+}

docs/api.rst

@@ -11,7 +11,8 @@ Automatic sleep staging & events detection
 .. _staging:
 
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
+    :nosignatures:
 
     SleepStaging
     art_detect
@@ -29,7 +30,8 @@ Hypnogram & sleep statistics
 .. _hgram:
 
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
+    :nosignatures:
 
     hypno_upsample_to_data
     hypno_upsample_to_sf
@@ -52,7 +54,8 @@ Spectral analyses
 .. _spectral:
 
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
+    :nosignatures:
 
     bandpower
     bandpower_from_psd
@@ -64,13 +67,13 @@ Spectral analyses
     stft_power
     topoplot
 
-
 Heart rate analysis
 -------------------
 
 .. _others:
 
 .. autosummary::
-   :toctree: generated/
+    :toctree: generated/
+    :nosignatures:
 
     hrv_stage