Migrate to mkdocs (LorenFrankLab#527)

.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish docs
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - closed
+  push:
+    branches:
+      - test_branch
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  repository-projects: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      REPO_OWNER: ${{ github.repository_owner }}
+    permissions:
+      contents: write
+      issues: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Python runtime
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup - pip & config
+        run: |
+          pip install -r requirements-docs.txt
+          git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Deploy
+        run: |
+          echo "OWNER: ${REPO_OWNER}"
+          bash ./docs/build-docs.sh push $REPO_OWNER
+        env:
+          USERNAME: github-actions[bot]
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -92,9 +92,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 
@@ -137,9 +134,6 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
-
 # mypy
 .mypy_cache/
 .dmypy.json
@@ -179,3 +173,11 @@ dj_local_conf.json
 !/.vscode/settings.json
 !/notebooks/dlc_scratch.png
 !/notebooks/dlc_existing.png
+
+# Documentation
+docs/site/
+docs/src/CHANGELOG.md
+docs/src/LICENSE.md
+docs/src/notebooks/
+!docs/src/images/*png
+temp*

.markdownlint.yaml

@@ -0,0 +1,13 @@
+# https://github.com/DavidAnson/markdownlint
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+MD007: false # permit indenting 4 spaces instead of 2
+MD013:
+    line_length: "80" # Line length limits
+    tables: false # disable for tables
+    code_blocks: false # disable for code blocks
+MD025: false # permit adjacent headings
+MD026: false # permit trailing punctuation in headings
+MD033: # HTML elements allowed
+    allowed_elements:
+        - "img"
+MD034: false # Bare URLs OK

CHANGELOG.md

@@ -1,38 +1,60 @@
-# 0.4.0 (May 22, 2023)
-- Updated call to `spikeinterface.preprocessing.whiten` to use dtype np.float16. #446,
+# Change Log
+
+## 0.4.1 (Unreleased)
+
+- Add mkdocs automated deployment
+
+## 0.4.0 (May 22, 2023)
+
+- Updated call to `spikeinterface.preprocessing.whiten` to use dtype np.float16.
+  #446,
 - Updated default spike sorting metric parameters. #447
-- Updated whitening to be compatible with recent changes in spikeinterface when using mountainsort. #449
-- Moved LFP pipeline to `src/spyglass/lfp/v1` and addressed related usability issues. #468, #478, #482, #484, #504
+- Updated whitening to be compatible with recent changes in spikeinterface when
+  using mountainsort. #449
+- Moved LFP pipeline to `src/spyglass/lfp/v1` and addressed related usability
+  issues. #468, #478, #482, #484, #504
 - Removed whiten parameter for clusterless thresholder. #454
 - Added plot to plot all DIO events in a session. #457
 - Added file sharing functionality through kachery_cloud. #458, #460
 - Pinned numpy version to `numpy<1.24`
 - Added scripts to add guests and collaborators as users. #463
 - Cleaned up installation instructions in repo README. #467
-- Added checks in decoding visualization to ensure time dimensions are the correct length.
+- Added checks in decoding visualization to ensure time dimensions are the
+  correct length.
 - Fixed artifact removed valid times. #472
 - Added codespell workflow for spell checking and fixed typos. #471
 - Updated LFP code to save LFP as `pynwb.ecephys.LFP` type. #475
 - Added artifact detection to LFP pipeline. #473
-- Replaced calls to `spikeinterface.sorters.get_default_params` with `spikeinterface.sorters.get_default_sorter_params`. #486
-- Updated position pipeline and added functionality to handle pose estimation through DeepLabCut. #367, #505
+- Replaced calls to `spikeinterface.sorters.get_default_params` with
+  `spikeinterface.sorters.get_default_sorter_params`. #486
+- Updated position pipeline and added functionality to handle pose estimation
+  through DeepLabCut. #367, #505
 - Updated `environment_position.yml`. #502
 - Renamed `FirFilter` class to `FirFilterParameters`. #512
 
-# 0.3.4 (March 30, 2023)
-- Fixed error in spike sorting pipeline referencing the "probe_type" column which is no longer accessible from the `Electrode` table. #437
-- Fixed error when inserting an NWB file that does not have a probe manufacturer. #433, #436
-- Fixed error when adding a new `DataAcquisitionDevice` and a new `ProbeType`. #436
-- Fixed inconsistency between capitalized/uncapitalized versions of "Intan" for DataAcquisitionAmplifier and DataAcquisitionDevice.adc_circuit. #430, #438
+## 0.3.4 (March 30, 2023)
+
+- Fixed error in spike sorting pipeline referencing the "probe_type" column
+  which is no longer accessible from the `Electrode` table. #437
+- Fixed error when inserting an NWB file that does not have a probe
+  manufacturer. #433, #436
+- Fixed error when adding a new `DataAcquisitionDevice` and a new `ProbeType`.
+  #436
+- Fixed inconsistency between capitalized/uncapitalized versions of "Intan" for
+  DataAcquisitionAmplifier and DataAcquisitionDevice.adc_circuit. #430, #438
+
+## 0.3.3 (March 29, 2023)
 
-# 0.3.3 (March 29, 2023)
 - Fixed errors from referencing the changed primary key for `Probe`. #429
 
-# 0.3.2 (March 28, 2023)
+## 0.3.2 (March 28, 2023)
+
 - Fixed import of `common_nwbfile`. #424
 
-# 0.3.1 (March 24, 2023)
+## 0.3.1 (March 24, 2023)
+
 - Fixed import error due to `sortingview.Workspace`. #421
 
-# 0.3.0 (March 24, 2023)
-To be added.
+## 0.3.0 (March 24, 2023)
+
+To be added.

LICENSE

@@ -1,7 +1,18 @@
 Copyright (c) 2020-present Loren Frank
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BEsq LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,27 +1,44 @@
-[![Import test](https://github.com/LorenFrankLab/spyglass/actions/workflows/workflow.yml/badge.svg)](https://github.com/LorenFrankLab/spyglass/actions/workflows/workflow.yml)
-
 # spyglass
 
-`spyglass` is a data analysis framework that facilitates the storage, analysis, visualization, and sharing of neuroscience data to support reproducible research. It is designed to be interoperable with the NWB format and integrates open-source tools into a coherent framework.
+[![Import test](https://github.com/LorenFrankLab/spyglass/actions/workflows/workflow.yml/badge.svg)](https://github.com/LorenFrankLab/spyglass/actions/workflows/workflow.yml)
+
+`spyglass` is a data analysis framework that facilitates the storage, analysis,
+visualization, and sharing of neuroscience data to support reproducible
+research. It is designed to be interoperable with the NWB format and integrates
+open-source tools into a coherent framework.
 
-Documentation can be found at - [https://lorenfranklab.github.io/spyglass/](https://lorenfranklab.github.io/spyglass/)
+Documentation can be found at -
+[https://lorenfranklab.github.io/spyglass/](https://lorenfranklab.github.io/spyglass/)
 
 ## Installation
 
-For installation instructions see - [https://lorenfranklab.github.io/spyglass/type/html/installation.html](https://lorenfranklab.github.io/spyglass/type/html/installation.html)
+For installation instructions see -
+[https://lorenfranklab.github.io/spyglass/type/html/installation.html](https://lorenfranklab.github.io/spyglass/type/html/installation.html)
 
 ## Tutorials
 
-The tutorials for `spyglass` is currently in the form of Jupyter Notebooks and can be found in the [notebooks](https://github.com/LorenFrankLab/spyglass/tree/master/notebooks) directory. We strongly recommend opening them in the context of `jupyterlab`.
+The tutorials for `spyglass` is currently in the form of Jupyter Notebooks and
+can be found in the
+[notebooks](https://github.com/LorenFrankLab/spyglass/tree/master/notebooks)
+directory. We strongly recommend opening them in the context of `jupyterlab`.
 
 ## Contributing
 
-See the [Developer's Note](https://lorenfranklab.github.io/spyglass/type/html/developer_notes.html) for contributing instructions found at - [https://lorenfranklab.github.io/spyglass/type/html/how_to_contribute.html](https://lorenfranklab.github.io/spyglass/type/html/how_to_contribute.html)
+See the [Developer's Note](https://lorenfranklab.github.io/spyglass/type/html/developer_notes.html)
+for contributing instructions found at -
+[https://lorenfranklab.github.io/spyglass/type/html/how_to_contribute.html](https://lorenfranklab.github.io/spyglass/type/html/how_to_contribute.html)
 
 ## License/Copyright
 
-License and Copyright notice can be found at [https://lorenfranklab.github.io/spyglass/type/html/copyright.html](https://lorenfranklab.github.io/spyglass/type/html/copyright.html)
+License and Copyright notice can be found at
+[https://lorenfranklab.github.io/spyglass/type/html/copyright.html](https://lorenfranklab.github.io/spyglass/type/html/copyright.html)
 
 ## Citation
 
-Kyu Hyun Lee, Eric Denovellis, Ryan Ly, Jeremy Magland, Jeff Soules, Alison Comrie, Jennifer Guidera, Rhino Nevers, Daniel Gramling, Philip Adenekan, Ji Hyun Bak, Emily Monroe, Andrew Tritt, Oliver Rübel, Thinh Nguyen, Dimitri Yatsenko, Joshua Chu, Caleb Kemere, Samuel Garcia, Alessio Buccino, Emily Aery Jones, Lisa Giocomo, and Loren Frank. Spyglass: A Data Analysis Framework for Reproducible and Shareable Neuroscience Research. Neuroscience Meeting Planner. San Diego, CA: Society for Neuroscience, 2022.
+Kyu Hyun Lee, Eric Denovellis, Ryan Ly, Jeremy Magland, Jeff Soules, Alison
+Comrie, Jennifer Guidera, Rhino Nevers, Daniel Gramling, Philip Adenekan, Ji
+Hyun Bak, Emily Monroe, Andrew Tritt, Oliver Rübel, Thinh Nguyen, Dimitri
+Yatsenko, Joshua Chu, Caleb Kemere, Samuel Garcia, Alessio Buccino, Emily Aery
+Jones, Lisa Giocomo, and Loren Frank. Spyglass: A Data Analysis Framework for
+Reproducible and Shareable Neuroscience Research. Neuroscience Meeting Planner.
+San Diego, CA: Society for Neuroscience, 2022.

config/add_dj_module.py

@@ -21,7 +21,9 @@ def add_module(module_name):
 
     # get a list of usernames
     for user in group.gr_mem:
-        file.write(f"GRANT ALL PRIVILEGES ON `{module_name}\_%`.* TO `{user}`@'%';\n")
+        file.write(
+            f"GRANT ALL PRIVILEGES ON `{module_name}\_%`.* TO `{user}`@'%';\n"
+        )
     file.flush()
 
     # run those commands in sql

config/add_dj_user.py

@@ -19,7 +19,9 @@ def add_user(user_name):
         f"GRANT ALL PRIVILEGES ON `{user_name}\_%`.* TO `{user_name}`@'%' IDENTIFIED BY 'temppass';\n"
     )
     for module in shared_modules:
-        file.write(f"GRANT ALL PRIVILEGES ON `{module}`.* TO `{user_name}`@'%';\n")
+        file.write(
+            f"GRANT ALL PRIVILEGES ON `{module}`.* TO `{user_name}`@'%';\n"
+        )
     file.write(f"GRANT SELECT ON `%`.* TO `{user_name}`@'%';\n")
     file.flush()
 

config/dj_config.py

@@ -16,6 +16,8 @@ def generate_config_yaml(filename: str, **kwargs):
     ----------
     filename : str
         The name of the file to generate
+    output : str
+        File type to generate. Either yaml or json
     **kwargs: list of parameters names and values that can include
         database_host : host name of system running mysql (default lmf-db.cin.ucsf.edu)
         database_port : port number for mysql server (default 3306)
@@ -27,7 +29,9 @@ def generate_config_yaml(filename: str, **kwargs):
     print("printing kwargs")
     print(kwargs)
     config["database.host"] = (
-        kwargs["database_host"] if "database_host" in kwargs else "lmf-db.cin.ucsf.edu"
+        kwargs["database_host"]
+        if "database_host" in kwargs
+        else "lmf-db.cin.ucsf.edu"
     )
     config["database.port"] = (
         kwargs["database_port"] if "database_port" in kwargs else 3306
@@ -50,15 +54,24 @@ def generate_config_yaml(filename: str, **kwargs):
     analysis_dir = data_dir / "analysis"
 
     config["stores"] = {
-        "raw": {"protocol": "file", "location": str(raw_dir), "stage": str(raw_dir)},
+        "raw": {
+            "protocol": "file",
+            "location": str(raw_dir),
+            "stage": str(raw_dir),
+        },
         "analysis": {
             "protocol": "file",
             "location": str(analysis_dir),
             "stage": str(analysis_dir),
         },
     }
     with open(filename, "w") as outfile:
-        yaml.dump(config, outfile, default_flow_style=False)
+        if filename.endswith("json"):
+            import json  # noqa: F821
+
+            json.dump(config, outfile, indent=2)
+        else:
+            yaml.dump(config, outfile, default_flow_style=False)
 
 
 def set_configuration(user_name: str, file_name: str = None):

docs/build-docs.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Run this script from repo root to serve site: > bash ./docs/build-docs.sh serve
+# Then, navigate to localhost:8000/ to inspect site, then ctrl+c to exit
+# For auto-reload during dev, use `mkdocs serve -f ./docs/mkdosc.yaml`
+
+
+# Copy top-level repo files for docs display
+cp ./CHANGELOG.md ./docs/src/
+cp ./LICENSE ./docs/src/LICENSE.md
+cp -r ./notebooks/ ./docs/src/
+
+# Get major version
+FULL_VERSION=$(grep -m 1 version pyproject.toml | tr -s ' ' | tr -d '"' | tr -d "'" | cut -d' ' -f3)
+export MAJOR_VERSION="${FULL_VERSION%.*}"
+echo "$MAJOR_VERSION"
+
+# Generate site docs
+mike deploy "$MAJOR_VERSION" --config ./docs/mkdocs.yml -b documentation
+
+# Label this version as latest, set as default
+mike alias "$MAJOR_VERSION" latest --config ./docs/mkdocs.yml -b documentation
+mike set-default latest --config ./docs/mkdocs.yml -b documentation
+
+# # Serve site to localhost
+if [ "$1" == "serve" ]; then # If first arg is serve, serve docs
+  mike serve --config ./docs/mkdocs.yml -b documentation
+elif [ "$1" == "push" ]; then # if first arg is push
+    if [ -z "$2" ]; then # When no second arg, use local git user
+        git_user=$(git config user.name)
+    else # Otherwise, accept second arg as git user
+        git_user="${2}"
+    fi # Push mike results to relevant branch
+    export url="https://github.com/${git_user}/spyglass.git"
+    git push "$url" documentation
+else
+    echo "Docs built. "
+    echo "  Add 'serve' as script arg to serve. "
+    echo "  Add 'push' to push to your fork."
+    echo "  Use additional arg to dictate push-to fork"
+fi