Overhaul docs with PyData Sphinx Theme (#194)

* remove `build/`, `pictures/`, and other files
+ No longer need tracking on this repo branch

* theme bootstrap --> pydata (with defaults)

* local --> remote picture loading

* Update intersphinx-mapping links

* rm time, os --> pathlib

* organize conf.py file

* remove api signatures

* add all pages to navbar

* html --> rst dropdowns in FAQ

* remove changelog toc bc now in sidebar

* minor styling

* try gh-pages action build

* add missing docs requirement

* minor header changes

* consistent rst indent spacing (4)

* heavy conf.py comments

* update build instructions

.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