Adding what's new and correct doc (NeuroTechX#200)

* add cache for poetry, datasets and html docs

* correct doc building error, add whatsnew, update class/function template

* adding gh function from braindecode/MNE

* correct cache path for docs, dont cache venv for windows test

.github/workflows/docs.yml

@@ -8,10 +8,9 @@ on:
 
 jobs:
   build_docs:
-    name: ${{ matrix.os }}, py-${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     strategy:
-      fail-fast: false
+      fail-fast: true
       matrix:
         os: [ubuntu-18.04]
         python-version: ["3.6"]
@@ -23,21 +22,34 @@ jobs:
         run: |
           mkdir ~/mne_data
 
-      - name: Cache datasets
-        uses: actions/cache@v2
-        with:
-          path: ~/mne_data
-          key: ${{ runner.os }}-${{ hashFiles('moabb/datasets/**') }}
-
       - name: Setup Python
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Install Poetry
+        uses: snok/[email protected]
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Cache poetry, datasets and docs
+        id: cached-poetry-dataset-docs
+        uses: actions/cache@v2
+        with:
+          key:
+            ${{ runner.os }}-${{ hashFiles('moabb/datasets/**', '**/poetry.lock') }}-doc
+          path: |
+            ~/mne_data
+            .venv
+            docs/build
+
       - name: Install dependencies
-        run: |
-          pip install poetry
-          poetry install -E external
+        if: steps.cached-poetry-dataset-docs.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root -E external
+
+      - name: Install library
+        run: poetry install --no-interaction -E external
 
       - name: Build docs
         run: |
@@ -59,6 +71,17 @@ jobs:
         os: [ubuntu-18.04]
 
     steps:
+      - name: Cache poetry, datasets and docs
+        id: cached-poetry-dataset-docs
+        uses: actions/cache@v2
+        with:
+          key:
+            ${{ runner.os }}-${{ hashFiles('moabb/datasets/**', '**/poetry.lock') }}-doc
+          path: |
+            ~/mne_data
+            .venv
+            docs/build
+
       - name: Checkout moabb.github.io
         uses: actions/checkout@v2
         with:

.github/workflows/test.yml

@@ -11,27 +11,54 @@ jobs:
     name: ${{ matrix.os }}, py-${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     strategy:
-      fail-fast: false
+      fail-fast: true
       matrix:
         os: [ubuntu-18.04, windows-latest, macOS-latest]
         python-version: ["3.6", "3.7", "3.8", "3.9"]
+    defaults:
+      run:
+        shell: bash
     steps:
       - uses: actions/checkout@v2
+
       - name: Setup Python
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
+
       - uses: pre-commit/[email protected]
+
+      - name: Install Poetry
+        uses: snok/[email protected]
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Load cached venv
+        if: runner.os != 'Windows'
+        id: cached-poetry-dependencies
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key:
+            venv-${{ matrix.os }}-py${{matrix.python-version}}-${{
+            hashFiles('**/poetry.lock') }}
+
       - name: Install dependencies
-        shell: bash
-        run: |
-          python -m pip install --upgrade pip poetry wheel
-          poetry install
+        if: |
+          (runner.os != 'Windows') &&
+          (steps.cached-poetry-dependencies.outputs.cache-hit != 'true')
+        run: poetry install --no-interaction --no-root
+
+      - name: Install library
+        run: poetry install --no-interaction
+
       - name: Run tests
-        shell: bash
         run: |
+          source $VENV
           poetry run python -m unittest moabb.tests
+
       - name: Run pipelines
-        shell: bash
         run: |
+          source $VENV
           poetry run python -m moabb.run --pipelines=./moabb/tests/test_pipelines/ --verbose

docs/source/README.md

@@ -1,3 +1,5 @@
+.. currentmodule:: moabb
+
 # Mother of all BCI Benchmarks
 
 ![banner](images/M.png)

docs/source/_templates/class.rst

@@ -4,7 +4,11 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
+   :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__,__hash__
+   :members:
 
-   {% block methods %}
-   .. automethod:: __init__
-   {% endblock %}
+.. include:: {{fullname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

docs/source/_templates/function.rst

@@ -4,3 +4,9 @@
 .. currentmodule:: {{ module }}
 
 .. autofunction:: {{ objname }}
+
+.. include:: {{ fullname }}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>

docs/source/conf.py

@@ -8,7 +8,9 @@
 
 # -- Path setup --------------------------------------------------------------
 
+import inspect
 import os
+import os.path as op
 import sys
 
 import matplotlib
@@ -18,6 +20,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import sphinx_bootstrap_theme
+from numpydoc import docscrape, numpydoc  # noqa
 
 # Sort tutorials and examples but filename
 from sphinx_gallery.sorting import FileNameSortKey
@@ -33,7 +36,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "moabb"
-copyright = "2018, Alexandre Barachant"
+copyright = "2018-2021, Alexandre Barachant, Sylvain Chevallier"
 author = "Alexandre Barachant, Vinay Jayaram, Sylvain Chevallier"
 
 # The short X.Y version
@@ -48,27 +51,115 @@
 #
 # needs_sphinx = '1.0'
 
+curdir = os.path.dirname(__file__)
+sys.path.append(os.path.abspath(os.path.join(curdir, "sphinxext")))
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
-    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.imgmath",
-    "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
-    "sphinx.ext.autosummary",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
+    "gh_substitutions",
     "m2r2",
+    "numpydoc",
 ]
 
+
+def linkcode_resolve(domain, info):  # noqa: C901
+    """Determine the URL corresponding to a Python object.
+    Parameters
+    ----------
+    domain : str
+        Only useful when 'py'.
+    info : dict
+        With keys "module" and "fullname".
+    Returns
+    -------
+    url : str
+        The code URL.
+    Notes
+    -----
+    This has been adapted to deal with our "verbose" decorator.
+    Adapted from SciPy (doc/source/conf.py).
+    """
+    import mne
+
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except Exception:
+            return None
+    # deal with our decorators properly
+    while hasattr(obj, "__wrapped__"):
+        obj = obj.__wrapped__
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        try:
+            fn = inspect.getsourcefile(sys.modules[obj.__module__])
+        except Exception:
+            fn = None
+    if not fn:
+        return None
+    fn = op.relpath(fn, start=op.dirname(mne.__file__))
+    fn = "/".join(op.normpath(fn).split(os.sep))  # in case on Windows
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except Exception:
+        lineno = None
+
+    if lineno:
+        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+    else:
+        linespec = ""
+
+    if "dev" in moabb.__version__:
+        kind = "master"
+    else:
+        kind = "maint/%s" % (".".join(mne.__version__.split(".")[:2]))
+    return "http://github.com/NeuroTechX/moabb/blob/%s/moabb/%s%s" % (  # noqa
+        kind,
+        fn,
+        linespec,
+    )
+
+
 napoleon_google_docstring = False
 napoleon_use_param = False
 napoleon_use_ivar = True
 
+numpydoc_show_class_members = True
+numpydoc_class_members_toctree = False
+numpydoc_attributes_as_param_list = True
+numpydoc_xref_param_type = True
+
 plot_include_source = True
 plot_formats = [("png", 90)]
 plot_html_show_formats = False
@@ -77,6 +168,8 @@
 sphinx_gallery_conf = {
     "examples_dirs": ["../../examples", "../../tutorials"],
     "gallery_dirs": ["auto_examples", "auto_tutorials"],
+    "doc_module": ("moabb", "mne"),
+    "backreferences_dir": "generated",
     "filename_pattern": "(/plot_|/tutorial_)",
     "default_thumb_file": "../images/M.png",
     "within_subsection_order": FileNameSortKey,
@@ -85,9 +178,9 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-autodoc_default_flags = ["inherited-members"]
+autodoc_default_flags = {"inherited-members": None}
 autosummary_generate = True
-numpydoc_show_class_members = True
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -264,7 +357,14 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/{.major}".format(sys.version_info), None),
+    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "matplotlib": ("https://matplotlib.org/", None),
+    "sklearn": ("http://scikit-learn.org/stable", None),
+    "mne": ("http://mne.tools/stable", None),
+}
 
 # -- Options for todo extension ----------------------------------------------
 

docs/source/datasets.rst

@@ -73,12 +73,18 @@ Base & Utils
     :template: class.rst
 
     base.BaseDataset
+
+
+.. autosummary::
+    :toctree: generated/
+    :template: function.rst
+
     download.data_path
-	 download.data_dl
-	 download.fs_issue_request
-	 download.fs_get_file_list
-	 download.fs_get_file_hash
-	 download.fs_get_file_id
-	 download.fs_get_file_name
+    download.data_dl
+    download.fs_issue_request
+    download.fs_get_file_list
+    download.fs_get_file_hash
+    download.fs_get_file_id
+    download.fs_get_file_name
     utils.dataset_search
     utils.find_intersecting_channels