feat(docs): improve dataset documentation with tags, feedback section, and visualization updates

.github/workflows/doc.yaml

@@ -6,12 +6,14 @@ on:
   push:
     branches:
       - "main"
+      - "develop"
   pull_request:
     branches:
       - '*' # all branches, including forks
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   docs:
@@ -114,11 +116,97 @@ jobs:
           cd docs
           uv run make html
 
-      # New step to deploy the docs to the gh-pages branch
-      - name: Deploy to GitHub Pages
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      # Upload documentation as artifact for all builds
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-html
+          path: ./docs/_build/html
+          retention-days: 14
+
+      # Deploy PR preview to surge.sh (optional - requires SURGE_TOKEN secret)
+      - name: Deploy PR Preview
+        if: github.event_name == 'pull_request'
+        id: deploy-preview
+        continue-on-error: true
+        env:
+          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
+        run: |
+          if [ -z "$SURGE_TOKEN" ]; then
+            echo "SURGE_TOKEN not configured, skipping live preview deployment"
+            exit 0
+          fi
+          npm install -g surge
+          DEPLOY_DOMAIN="eegdash-pr-${{ github.event.pull_request.number }}.surge.sh"
+          surge ./docs/_build/html $DEPLOY_DOMAIN --token $SURGE_TOKEN
+          echo "preview_url=https://$DEPLOY_DOMAIN" >> $GITHUB_OUTPUT
+
+      # Comment on PR with preview link
+      - name: Comment PR with Preview Link
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const previewUrl = '${{ steps.deploy-preview.outputs.preview_url }}' || '';
+            const artifactUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const surgeSuccess = '${{ steps.deploy-preview.outcome }}' === 'success';
+
+            let body = `## 📚 Documentation Preview\n\n`;
+
+            if (surgeSuccess && previewUrl) {
+              body += `| Resource | Link |\n`;
+              body += `|----------|------|\n`;
+              body += `| 🌐 **Live Preview** | [${previewUrl}](${previewUrl}) |\n`;
+              body += `| 📦 Download Artifact | [View Workflow Run](${artifactUrl}) |\n\n`;
+              body += `> This preview will be available for 14 days. The live preview updates with each push to this PR.`;
+            } else {
+              body += `📦 **[Download Documentation Artifact](${artifactUrl})**\n\n`;
+              body += `> Download the \`documentation-html\` artifact from the workflow run to view the docs locally.\n\n`;
+              body += `💡 *To enable live previews, add a \`SURGE_TOKEN\` secret to this repository. See [surge.sh](https://surge.sh) for setup instructions.*`;
+            }
+
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.type === 'Bot' &&
+              comment.body.includes('Documentation Preview')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: body
+              });
+            }
+      # we are only deploying from develop for now onwards
+      # # Deploy the docs to the gh-pages branch (main and develop)
+      # - name: Deploy to GitHub Pages (main)
+      #   if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      #   uses: peaceiris/actions-gh-pages@v4
+      #   with:
+      #     github_token: ${{ secrets.GITHUB_TOKEN }}
+      #     publish_dir: ./docs/_build/html
+      #     destination_dir: archive
+      #     keep_files: true
+
+      - name: Deploy to GitHub Pages (develop)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/build/html
+          publish_dir: ./docs/_build/html
           cname: eegdash.org

.github/workflows/tests.yml

@@ -112,7 +112,7 @@ jobs:
     - name: Run Tests
       env:
         EEGDASH_API_TOKEN: ${{ secrets.EEGDASH_API_TOKEN }}
-      run: pytest -vvv -s --tb=long --durations=0 --log-cli-level=INFO --cov=eegdash --cov-report=xml tests --verbose 
+      run: pytest -vvv -s --tb=long --durations=0 --log-cli-level=INFO --cov=eegdash --cov-report=xml -o "addopts=-ra --durations=10" tests --verbose 
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v5

.gitignore

@@ -33,9 +33,11 @@ cover
 data/
 digestion_output/
 dist/
+# Documentation
+docs/_build/
+docs/build/
 docs/auto_examples/
 docs/auto_tutorials/
-docs/build/
 docs/modules/generated/
 docs/source/_static/dataset_generated/
 docs/source/api/api_dataset.rst
@@ -59,3 +61,5 @@ tests/.testeegdash/
 tests/data/
 */*/test_cache/*
 test_cache/*
+CLAUDE.md
+.claude/

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
         - --select=E,W,F,D,I,NPY201
         - --ignore=E402,E501,D100,D101,D102,D103,D104,D105,D107,D205,D400,D415,D417,F403,D401,E741,E722,D419
         files: ^(eegdash|docs|notebooks|scripts|tests)/
-        exclude: (\.ipynb$|docs/prepare_summary_tables\.py$)
+        exclude: (\.ipynb$)
     -   id: ruff
         name: ruff examples
         args:
@@ -53,3 +53,12 @@ repos:
     hooks:
     -   id: blacken-docs
         exclude: ^.github|CONTRIBUTING.md|README.md|docs/|examples/|notebooks/|scripts/|tests/
+-   repo: local
+    hooks:
+    -   id: no-nested-functions
+        name: Check for nested function definitions
+        entry: python scripts/check_nested_functions.py
+        language: python
+        types: [python]
+        files: ^(eegdash|docs|scripts)/
+        exclude: (\.ipynb$|docs/source/generated/|docs/_build/)

README.md

@@ -8,7 +8,7 @@
 [![Downloads](https://pepy.tech/badge/eegdash)](https://pepy.tech/project/eegdash)
 [![Coverage](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Feegdash%2FEEGDash%2Fmain%2Fcoverage.json&query=%24.totals.percent_covered_display&suffix=%25&label=coverage)](https://github.com/eegdash/EEGDash/blob/main/coverage.json)
 
-To leverage recent and ongoing advancements in large-scale computational methods and to ensure the preservation of scientific data generated from publicly funded research, the EEG-DaSh data archive will create a data-sharing resource for MEEG (EEG, MEG) data contributed by collaborators for machine learning (ML) and deep learning (DL) applications. 
+To leverage recent and ongoing advancements in large-scale computational methods and to ensure the preservation of scientific data generated from publicly funded research, the EEG-DaSh data archive will create a data-sharing resource for MEEG (EEG, MEG) data contributed by collaborators for machine learning (ML) and deep learning (DL) applications
 
 ## Data source
 

codecov.yml

@@ -0,0 +1,23 @@
+coverage:
+  precision: 2
+  round: down
+  range: "60...100"
+
+  status:
+    project:
+      default:
+        # Allow coverage to drop by up to 5% before failing
+        threshold: 5%
+        # Only fail if coverage drops below 60%
+        target: 60%
+    patch:
+      default:
+        # New code should have at least 70% coverage
+        target: 70%
+        # Allow some flexibility for patches
+        threshold: 10%
+
+comment:
+  layout: "reach,diff,flags,files"
+  behavior: default
+  require_changes: false

docs/Makefile

@@ -1,15 +1,18 @@
 # Minimal makefile for Sphinx documentation
+#
+
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 PKG ?= eegdash
 APIDIR := $(SOURCEDIR)/api
 
+.PHONY: help clean apidoc html html-noplot html-fast
+
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: apidoc
 apidoc:
 	# Generate full API docs, then prune duplicates covered by autosummary
 	@rm -f "$(APIDIR)"/dataset/eegdash.features*
@@ -18,24 +21,23 @@ apidoc:
 
 
 # Standard build runs examples
-html: apidoc 
+html: apidoc
+	python prepare_summary_tables.py --target $(BUILDDIR)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Fast build: do NOT execute examples (sphinx-gallery)
-.PHONY: html-noplot
-html-noplot: apidoc 
+html-noplot: apidoc
 	@python prepare_summary_tables.py --target $(BUILDDIR)
 	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" \
 		$(SPHINXOPTS) -D sphinx_gallery_conf.plot_gallery=0 $(O)
 
 # Very fast build: limit datasets to 5
-.PHONY: html-fast
 html-fast: apidoc
 	@EEGDASH_DOC_LIMIT=5 python prepare_summary_tables.py --target $(BUILDDIR)
 	@EEGDASH_DOC_LIMIT=5 $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" \
 		$(SPHINXOPTS) -D sphinx_gallery_conf.plot_gallery=0 $(O)
 
 # Custom clean target to remove generated API docs and build files
-.PHONY: clean
 clean:
 	@echo "Removing generated API documentation..."
 	@rm -rf "$(APIDIR)/dataset"
@@ -47,12 +49,13 @@ clean:
 	@rm -rf "$(SOURCEDIR)/generated"
 	@rm -rf "$(SOURCEDIR)/gen_modules"
 	@echo "Removing build directory..."
-	@rm -rf "$(BUILDDIR)"
+	@rm -rf "$(BUILDDIR)" build
 	@echo "Clean completed."
 
-.PHONY: help apidoc
-Makefile: ;          
+# Catch-all target for other sphinx-build formats
+# Prevent Makefile from matching the catch-all rule
+Makefile: ;
 
 %: Makefile
-	@python prepare_summary_tables.py --target $(BUILDDIR)
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	python prepare_summary_tables.py --target $(BUILDDIR)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/plot_dataset/__init__.py

@@ -1,6 +1,7 @@
 """Plot generation utilities for EEGDash documentation."""
 
 from .bubble import generate_dataset_bubble  # noqa: F401
+from .clinical_breakdown import generate_clinical_stacked_bar  # noqa: F401
 from .colours import (  # noqa: F401
     CANONICAL_MAP,
     COLUMN_COLOR_MAPS,
@@ -9,6 +10,7 @@
     TYPE_COLOR_MAP,
     hex_to_rgba,
 )
+from .growth import generate_dataset_growth  # noqa: F401
 from .plot_sankey import generate_dataset_sankey  # noqa: F401
 from .ridgeline import generate_modality_ridgeline  # noqa: F401
 from .treemap import generate_dataset_treemap  # noqa: F401