MNT: Add documentation to GitHub Pages (#85)

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: "Render Documentation"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup headless display
+      uses: pyvista/setup-headless-display-action@main
+      with:
+        qt: true
+        pyvista: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install requirements
+      run: |
+          python -m pip install --upgrade pip
+          pip install PySide6
+          pip install -ve ".[docs]"
+    - name: Build docs
+      run: |
+          cd ./docs
+          make html
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v4
+      if: github.ref == 'refs/heads/main'
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

.github/workflows/run_tests.yml

@@ -35,7 +35,7 @@ jobs:
           qt: true
           pyvista: false
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
       - name: Installation with dependencies

.gitignore

@@ -1,150 +1,19 @@
-# Created by .ignore support plugin (hsz.mobi)
-### Python template
-# Byte-compiled / optimized / DLL files
+# Python
 __pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
 .pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-doc/build/
-doc/generated
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
+*.egg-info/
+dist/
+.venv/
 venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
+.ipynb_checkpoints/
 
 # PyCharm Project-Settings
-.idea/*
+.idea/
 
 # VSCode
-.vscode/*
+.vscode/
 
-# Misc
-mne_pipeline_hd/environment.yml
+# Documentation
+docs/build/
+docs/generated/
+docs/source/generated

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2019-2023, authors of mne-pipeline-hd
+Copyright (c) 2019-2024, authors of mne-pipeline-hd
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/source/_static/versions.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "0.4 (development)",
+    "version": "dev",
+    "url": "https://github.com/marsipu/mne-pipeline-hd"
+  }
+]

docs/source/api/index.rst

@@ -0,0 +1,8 @@
+.. automodule:: mne_pipeline_hd.gui.parameter_widgets
+   :no-members:
+   :no-inherited-members:
+
+.. toctree::
+   :maxdepth: 2
+
+   parameter_widgets.rst

doc/source/parameter_widgets.rst → docs/source/api/parameter_widgets.rst

@@ -3,6 +3,12 @@ Parameter Widgets
 
 .. currentmodule:: mne_pipeline_hd.gui.parameter_widgets
 
+:py:mod:`mne.datasets`:
+
+.. automodule:: mne_pipeline_hd.gui.parameter_widgets
+   :no-members:
+   :no-inherited-members:
+
 .. autosummary::
    :toctree: ../generated
 

doc/source/conf.py → docs/source/conf.py

@@ -4,34 +4,43 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-import importlib
 
 # -- Path setup --------------------------------------------------------------
 
-import sys
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 from datetime import datetime, timezone
-from os.path import dirname, abspath, join
+from importlib.metadata import version
+
+# import sys
+
+# from os.path import dirname, abspath, join
+
+# curdir = dirname(__file__)
+# sys.path.append(abspath(join(curdir, "..", "..", "mne_pipeline_hd")))
+
+# # Import module because of annoying import problem on CIs
+from mne_pipeline_hd.gui import parameter_widgets
 
-curdir = dirname(__file__)
-sys.path.append(abspath(join(curdir, "..", "..", "mne_pipeline_hd")))
+module_list = list()
+module_list.append(parameter_widgets)
 
 # -- Project information -----------------------------------------------------
 project = "mne-pipeline-hd"
-author = "Martin Schulz"
+author = "Martin G. Schulz"
 
 td = datetime.now(tz=timezone.utc)
 copyright = (
-    f"2018-{datetime.now().year}, {author}, "
+    f"2019-{datetime.now().year}, {author}, "
     f'Last updated {td.strftime("%Y-%m-%d %H:%M %Z")}'
 )
 
 # The full version, including alpha/beta/rc tags
-release = importlib.metadata.version("mne_pipeline_hd")
+release = version("mne_pipeline_hd")
+# The short X.Y version.
+version = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 
@@ -54,6 +63,31 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
+switcher_version_match = "dev" if ".dev" in version else version
+html_theme_options = {
+    "icon_links": [
+        dict(
+            name="GitHub",
+            url="https://github.com/marsipu/mne-pipeline-hd",
+            icon="fa-brands fa-square-github fa-fw",
+        ),
+    ],
+    "icon_links_label": "External Links",
+    "navbar_end": [
+        "theme-switcher",
+        "version-switcher",
+        "navbar-icon-links",
+    ],
+    "navbar_align": "left",
+    "navbar_persistent": ["search-button"],
+    "footer_start": ["copyright"],
+    "secondary_sidebar_items": ["page-toc", "edit-this-page"],
+    # Todo: Insert versions url from webpage
+    # "switcher": {
+    #     "json_url": "<version-url>/versions.json",
+    #     "version_match": switcher_version_match,
+    # },
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/source/development/index.rst

@@ -0,0 +1 @@
+This is the development main page.

docs/source/documentation/index.rst

@@ -0,0 +1 @@
+This is the installation main page.