Add tutorial notebook renders

Author: CBroz1

.gitignore

@@ -102,6 +102,7 @@ ENV/
 
 # mkdocs documentation
 docs/site
+docs/src/tutorials/*ipynb
 
 # mypy
 .mypy_cache/

cspell.json

@@ -68,6 +68,7 @@
         "imrotbl",
         "imshow",
         "inlinehilite",
+        "ipynb",
         "ipywidgets",
         "kcoords",
         "Klusta",

docs/.docker/pip_requirements.txt

@@ -7,4 +7,5 @@ mdx-truly-sane-lists
 mkdocs-gen-files
 mkdocs-literate-nav
 mkdocs-exclude-search
-mkdocs-markdownextradata-plugin
+mkdocs-markdownextradata-plugin
+mkdocs-jupyter

docs/docker-compose.yaml

@@ -28,9 +28,17 @@ services:
       - |
         git config --global --add safe.directory /main
         set -e
+        export ELEMENT_UNDERSCORE=$$(echo $${PACKAGE} | sed 's/element_//g')
+        export ELEMENT_HYPHEN=$$(echo $${ELEMENT_UNDERSCORE} | sed 's/_/-/g')
         export PATCH_VERSION=$$(cat /main/$${PACKAGE}/version.py | grep -oE '\d+\.\d+\.[a-z0-9]+')
+        git clone https://github.com/datajoint/workflow-$${ELEMENT_HYPHEN}.git /main/delete || true
+        if [ -d /main/delete/ ]; then
+          mv /main/delete/workflow_$${ELEMENT_UNDERSCORE} /main/
+          mv /main/delete/notebooks/*ipynb /main/docs/src/tutorials/
+          rm -fR /main/delete
+        fi
         if echo "$${MODE}" | grep -i live &>/dev/null; then
-            mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
+            mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80 2>&1 | tee docs/temp_mkdocs.log
         elif echo "$${MODE}" | grep -iE "qa|push" &>/dev/null; then
             echo "INFO::Delete gh-pages branch"
             git branch -D gh-pages || true

docs/mkdocs.yaml

@@ -7,7 +7,19 @@ repo_name: datajoint/element-array-ephys
 nav:
   - Element Array Ephys: index.md
   - Concepts: concepts.md
-  - Tutorials: tutorials.md
+  - Tutorials: 
+    - Overview: tutorials/index.md
+    - Data Download: tutorials/00-data-download-optional.ipynb
+    - Configure: tutorials/01-configure.ipynb
+    - Workflow Structure: tutorials/02-workflow-structure-optional.ipynb
+    - Process: tutorials/03-process.ipynb
+    - Automate: tutorials/04-automate-optional.ipynb
+    - Explore: tutorials/05-explore.ipynb
+    - Drop: tutorials/06-drop-optional.ipynb
+    - Downstream Analysis: tutorials/07-downstream-analysis.ipynb
+    - Visualizations: tutorials/10-data_visualization.ipynb
+    - Electrode Localization: tutorials/08-electrode-localization.ipynb
+    - NWB Export: tutorials/09-NWB-export.ipynb
   - Citation: citation.md
   - API: api/ # defer to gen-files + literate-nav
   - Changelog: changelog.md
@@ -92,6 +104,12 @@ plugins:
   #       "index.md": "getting_started.md"
   - mkdocstrings:
       default_handler: python
+      handlers:
+        python:
+          options:
+            members_order: source
+            group_by_category: false
+            line_length: 88
   - gen-files:
       scripts:
       - ./src/api/make_pages.py
@@ -100,6 +118,8 @@ plugins:
   - exclude-search:
       exclude:
         - "*/navigation.md"
+  - mkdocs-jupyter:
+      ignore_h1_titles: True
 markdown_extensions:
   - attr_list
   - toc:
@@ -120,6 +140,7 @@ markdown_extensions:
       linenums: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
+  - footnotes
 
 extra:
   PATCH_VERSION: !ENV PATCH_VERSION

docs/src/api/make_pages.py

@@ -7,24 +7,10 @@
 import mkdocs_gen_files
 from pathlib import Path
 import os
-import subprocess
 
 package = os.getenv("PACKAGE")
 
 element = package.split("_", 1)[1]
-if not Path(f"workflow_{element}").is_dir():
-    try:
-        subprocess.run(
-            f"git clone https://github.com/datajoint/workflow-{element.replace('_','-')}.git /main/delete".split(
-                " "
-            ),
-            check=True,
-            timeout=5,
-        )
-        os.system(f"mv /main/delete/workflow_{element} /main/")
-        os.system("rm -fR /main/delete")
-    except subprocess.CalledProcessError:
-        pass  # no repo found
 
 nav = mkdocs_gen_files.Nav()
 for path in sorted(Path(package).glob("**/*.py")) + sorted(

docs/src/index.md

@@ -26,4 +26,4 @@ developed to handle various use cases of this pipeline and workflow:
 
 Visit the [Concepts page](./concepts.md) for more information about the use cases of
 `ephys` schemas and an explanation of the tables. To get started with building your own
-data pipeline, visit the [Tutorials page](./tutorials.md).
+data pipeline, visit the [Tutorials page](./tutorials/index.md).

docs/src/tutorials.md

@@ -0,0 +1,54 @@
+# Tutorials
+
+## Installation
+
+Installation of the Element requires an integrated development environment and database.
+Instructions to setup each of the components can be found on the
+[User Instructions](https://datajoint.com/docs/elements/user-guide/) page.  These
+instructions use the example
+[workflow for Element Array Ephys](https://github.com/datajoint/workflow-array-ephys),
+which can be modified for a user's specific experimental requirements.  This example
+workflow uses several Elements (Lab, Animal, Session, Event, and Electrophysiology) to construct
+a complete pipeline, and is able to ingest experimental metadata and run model training
+and inference.
+
+### Videos
+
+The [Element Array Ephys tutorial](https://youtu.be/KQlGYOBq7ow?t=3658) gives an
+overview of the workflow files and notebooks as well as core concepts related to
+Electrophysiology.
+
+[![YouTube tutorial](https://img.youtube.com/vi/KQlGYOBq7ow/0.jpg)](https://youtu.be/KQlGYOBq7ow?t=3658)
+
+### Notebooks
+
+Each of the notebooks in the workflow
+([download here](https://github.com/datajoint/workflow-array-ephys/tree/main/notebooks)
+steps through ways to interact with the Element itself. For convenience, these notebooks
+are also rendered as part of this site. To try out the Elements notebooks in an online
+Jupyter environment with access to example data, visit
+[CodeBook](https://codebook.datajoint.io/). (Electrophysiology notebooks coming soon!)
+
+- [Data Download](./00-data-download-optional.ipynb) highlights how to use DataJoint
+  tools to download a sample model for trying out the Element.
+- [Configure](./01-configure.ipynb) helps configure your local DataJoint installation to
+  point to the correct database.
+- [Workflow Structure](./02-workflow-structure-optional.ipynb) demonstrates the table
+   architecture of the Element and key DataJoint basics for interacting with these
+   tables.
+- [Process](./03-process.ipynb) steps through adding data to these tables and launching
+   key Electrophysiology features, like model training.
+- [Automate](./04-automate-optional.ipynb) highlights the same steps as above, but
+  utilizing all built-in automation tools.
+- [Explore](./05-explore.ipynb) demonstrates how to fetch data from the Element.
+- [Drop schemas](./06-drop-optional.ipynb) provides the steps for dropping all the
+  tables to start fresh.
+- [Downstream Analysis](./07-downstream-analysis.ipynb) highlights how to link
+   this Element to Element Event for event-based analyses.
+- [Visualizations](./10-data_visualization.ipynb) highlights how to use a built-in module
+   for visualizing units, probes and quality metrics.
+- [Electrode Localization](./08-electrode-localization.ipynb) demonstrates how to link
+  this Element to
+  [Element Electrode Localization](https://datajoint.com/docs/elements/element-electrode-localization/).
+- [NWB Export](./09-NWB-export.ipynb) highlights the export functionality available for the
+  `no-curation` schema.