make documentation buildable in 2024 :) (#209)

* make documentation buildable in 2024 :)

* document dependencies for building the docs in the readme

---------

Co-authored-by: Martin Billinger-Finke <[email protected]>

Author: mbillingr

README.md

@@ -37,3 +37,21 @@ To run the examples on Linux, invoke the following commands inside the SCoT dire
 etc.
 
 Note that the example data from https://github.com/SCoT-dev/scot-data needs to be available. The `scot-data` package must be on Python's search path.
+
+
+### Building the docs
+
+In February 2024 we managed to build the docs with the following package versions:
+
+```
+[tool.poetry.dependencies]
+python = "^3.11"
+sphinx = "^7.2.6"
+matplotlib = "^3.8.3"
+scipy = "^1.12.0"
+scikit-learn = "^1.4.1.post1"
+```
+
+Note that these are the most recent versions at the moment, so it is likely that future versions will just work.
+When using a newer version of sphinx, it may be necessary to update the subrepository in doc/sphinxext/numpydoc.
+

doc/README.md

@@ -0,0 +1,8 @@
+# Updating the docs
+
+1. run `generate_apidoc.sh`
+2. run `make.py`
+3. fix any errors and repeat steps 1-2 as often as necessary
+4. (ignore that building the latex docs fails)
+5. copy the content of build/html into the scot-doc repository, commit, push
+

doc/source/conf.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 #
 # SCoT documentation build configuration file, created by
 # sphinx-quickstart on Thu Jan 23 12:52:18 2014.
@@ -31,7 +30,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
 #    'matplotlib.sphinxext.mathmpl',
-    'matplotlib.sphinxext.only_directives',
+#    'matplotlib.sphinxext.only_directives',  # requires matplotlib <2.2.x
     'matplotlib.sphinxext.plot_directive',
 #    'matplotlib.sphinxext.ipython_directive',
     'sphinx.ext.autosummary',
@@ -211,7 +210,7 @@
 #'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
-'preamble': '\usepackage{amssymb}',
+'preamble': r'\usepackage{amssymb}',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

doc/source/pyplots/ellipses.py

@@ -4,7 +4,7 @@
 delta = 45.0 # degrees
 
 angles = arange(0, 360+delta, delta)
-ells = [Ellipse((1, 1), 4, 2, a) for a in angles]
+ells = [Ellipse((1, 1), 4, 2, angle=a) for a in angles]
 
 a = subplot(111, aspect='equal')
 

doc/sphinxext/gen_gallery.py

@@ -151,9 +151,7 @@ def gen_gallery(app, doctree):
         fh.write(content)
         fh.close()
 
-    for key in app.builder.status_iterator(
-            iter(thumbnails.keys()), "generating thumbnails... ",
-            length=len(thumbnails)):
+    for key in thumbnails.keys():
         if out_of_date(key, thumbnails[key]):
             image.thumbnail(key, thumbnails[key], 0.3)
 

doc/sphinxext/gen_rst.py

@@ -64,7 +64,6 @@ def generate_example_rst(app):
 SCoT Examples
 ####################
 
-.. htmlonly::
 
     :Release: |version|
     :Date: |today|
@@ -98,7 +97,6 @@ def generate_example_rst(app):
 %s Examples
 ##############################################
 
-.. htmlonly::
 
     :Release: |version|
     :Date: |today|

doc/sphinxext/numpydoc

@@ -11,7 +11,7 @@
     from sklearn.discriminant_analysis import LinearDiscriminantAnalysis as LDA
 except ImportError:
     from sklearn.lda import LDA
-from sklearn.cross_validation import KFold
+from sklearn.model_selection import KFold
 from sklearn.metrics import confusion_matrix
 
 import scot.xvschema
@@ -58,7 +58,7 @@
 
 # Initialize cross-validation
 nfolds = 10
-kf = KFold(len(triggers), n_folds=nfolds)
+kf = KFold(n_splits=nfolds)
 
 # LDA requires numeric class labels
 cl = np.unique(classes)
@@ -68,7 +68,7 @@
 lda = LDA()
 cm = np.zeros((2, 2))
 fold = 0
-for train, test in kf:
+for train, test in kf.split(data):
     fold += 1
 
     # Perform CSPVARICA

examples/misc/features.py

@@ -42,7 +42,7 @@
 data -= np.mean(data, axis=1, keepdims=True)
 
 # pre-transform data with a PCA
-myunmix, mymix, data = scot.config.backend['pca'](data, 0.99)
+myunmix, mymix, data = scot.backend['pca'](data, 0.99)
 
 print('Remaining data components:', data.shape[1])
 print('Note that the Topoplots still map to all 45 EEG channels.')

examples/test/premixing.py

@@ -35,15 +35,15 @@ def fetch(dataset="mi", datadir=datadir):
 
     Returns
     -------
-        data : list of dicts
-            The data set is stored in a list, where each list element
-            corresponds to data from one subject. Each list element is a
-            dictionary with the following keys:
-              "eeg" ... EEG signals
-              "triggers" ... Trigger latencies
-              "labels" ... Class labels
-              "fs" ... Sample rate
-              "locations" ... Channel locations
+    data : list of dicts
+        The data set is stored in a list, where each list element
+        corresponds to data from one subject. Each list element is a
+        dictionary with the following keys:
+        - "eeg" ... EEG signals
+        - "triggers" ... Trigger latencies
+        - "labels" ... Class labels
+        - "fs" ... Sample rate
+        - "locations" ... Channel locations
     """
     if dataset not in datasets:
         raise ValueError("Example data '{}' not available.".format(dataset))
@@ -65,7 +65,7 @@ def fetch(dataset="mi", datadir=datadir):
         with open(fullfile, "rb") as f:  # check if MD5 of downloaded file matches original hash
             hash = hashlib.md5(f.read()).hexdigest()
         if hash != md5[n]:
-            raise MD5MismatchError("MD5 hash of {} does not match {}.".format(fullfile, md5[n]))
+            raise MD5MismatchError("MD5 hash of {} {} does not match {}.".format(fullfile, hash, md5[n]))
         data.append(convert(dataset, loadmat(fullfile)))
 
     return data