Basic introductory material for GUIDE tutorials

.gitignore

@@ -1,6 +1,7 @@
 *.[oa]
 *~
 
+_build
 dist
 out
 tests/screenshots

docs/index.rst

@@ -19,5 +19,6 @@ The resulting files are fully compliant with the best practices expected of the
    :maxdepth: 2
 
    installation
+   tutorials/index
    format_support
    developer_guide

docs/tutorials/dataset.rst

@@ -0,0 +1,48 @@
+Dataset Generation
+==================
+
+Our tutorials focus on converting extracellular electrophysiology data in the SpikeGLX and Phy formats.
+To get you started as quickly as possible, we’ve created a way to generate this Neuropixel-like dataset at the click of a button!
+
+.. note::
+  The **SpikeGLX** data format stores electrophysiology recordings.
+
+  The **Phy** data format stores spike sorting results.
+
+Navigate to the **Settings** page using the main sidebar. Then press the **Generate** button in the top-right corner to initiate the dataset creation.
+
+.. figure:: ./screenshots/dataset-creation.png
+  :align: center
+  :alt: Dataset Creation Screen
+
+  Press the Generate button on the Settings page to create the dataset.
+
+The generated dataset will be organized as follows:
+
+.. code-block:: bash
+
+    dataset/
+    ├── mouse1/
+    │   ├── mouse1_Session1/
+    │   │   ├── mouse1_Session1_g0/
+    │   │   │   ├── mouse1_Session1_g0_imec/
+    │   │   │   │   ├── mouse1_Session1_g0_imec.ap.bin
+    │   │   │   │   ├── mouse1_Session1_g0_imec.ap.meta
+    │   │   │   │   ├── mouse1_Session1_g0_imec.lf.bin
+    │   │   │   │   └── mouse1_Session1_g0_imec.lf.meta
+    │   │   │   └── mouse1_Session1_phy/
+    │   │   │
+    │   │   └── mouse1_Session2/
+    │   │       ├── mouse1_Session2_g0/
+    │   │       │   ...
+    │   │       └── mouse1_Session2_phy/
+    │   │           ...
+    │   │
+    └── mouse2/
+        ├── mouse2_Session1/
+        │   ...
+        │
+        └── mouse2_Session2/
+            ...
+
+Now you’re ready to start your first conversion using the NWB GUIDE!

docs/tutorials/dataset_publication.rst

@@ -0,0 +1,3 @@
+Dataset Publication
+=======================================
+Coming soon...

docs/tutorials/index.rst

@@ -0,0 +1,17 @@
+Tutorials
+=======================================
+The NWB Graphical User Interface for Data Entry (GUIDE) is a desktop tool for converting neurophysiological data
+to the Neurodata Without Borders (NWB) format and uploading to the DANDI Archive. In these tutorials, we detail this
+process from initial setup to final upload.
+
+Before you begin these tutorials, **you'll need to generate the tutorial dataset** using the instructions on the Dataset page.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   dataset
+   single_session
+   multiple_sessions
+   dataset_publication
+   next_steps

docs/tutorials/multiple_sessions.rst

@@ -0,0 +1,3 @@
+Managing Multiple Sessions
+==========================
+Coming soon...

docs/tutorials/next_steps.rst

@@ -0,0 +1,3 @@
+What's Next?
+=======================================
+Coming soon...

docs/tutorials/single_session.rst

@@ -0,0 +1,3 @@
+Converting a Single Session
+=======================================
+Coming soon...

package.json

@@ -39,7 +39,8 @@
     "deploy:electron:linux": "electron-builder build --linux --publish always",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "chromatic": "npx chromatic"
+    "chromatic": "npx chromatic",
+    "build:docs": "sphinx-build -b html docs/ _build/html/"
   },
   "lint-staged": {
     "./**/*.{html|css|js|md|yml}": [

tests/e2e.test.ts

@@ -7,19 +7,25 @@ import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 
 import paths from "../paths.config.json" assert { type: "json" };
+import { ScreenshotOptions } from 'puppeteer'
 
 // ------------------------------------------------------------------
 // ------------------------ Path Definitions ------------------------
 // ------------------------------------------------------------------
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const screenshotPath = join(__dirname, 'screenshots')
+const screenshotPath = join(__dirname, '..', 'docs', 'tutorials', 'screenshots')
 const guideRootPath = join(homedir(), paths.root)
 const testRootPath = join(guideRootPath, '.test')
 const testDataRootPath = join(testRootPath, 'test-data')
 const testDataPath = join(testDataRootPath, 'data')
 const testDatasetPath = join(testDataRootPath, 'dataset')
 
+const windowDims = {
+  width: 1280,
+  height: 800
+}
+
 const alwaysDelete = [
   join(testRootPath, 'pipelines'),
   join(testRootPath, 'conversions'),
@@ -65,7 +71,8 @@ const subjectInfo = {
   age: 'P30D'
 }
 
-const regenerateTestData = !existsSync(testDataRootPath) || false // Generate only if doesn't exist
+// const regenerateTestData = !existsSync(testDataRootPath) || false // Generate only if doesn't exist
+const regenerateTestData = true // Force regeneration
 
 const dandiInfo = {
   id: '212750',
@@ -96,11 +103,14 @@ describe('E2E Test', () => {
 
   const references = connect()
 
-  let nScreenshots = 0
-  const takeScreenshot = async (label, delay = 0) => {
+  const takeScreenshot = async (label, delay = 0, options: ScreenshotOptions = { fullPage: true }) => {
     if (delay) await sleep(delay)
-    await references.page.screenshot({ path: join(screenshotPath, `${nScreenshots}-${label}.png`), fullPage: true });
-    nScreenshots++
+
+    const pathToScreenshot = join(screenshotPath, `${label}.png`)
+
+    if (existsSync(pathToScreenshot)) return console.error(`Screenshot already exists: ${pathToScreenshot}`)
+
+    await references.page.screenshot({ path: pathToScreenshot, ...options });
   }
 
   const evaluate = async (...args) => await references.page.evaluate(...args)
@@ -150,7 +160,18 @@ describe('E2E Test', () => {
 
     datasetTestFunction('Create tutorial dataset', async () => {
 
-      const outputLocation = await evaluate(async () => {
+      const x = 250 // Sidebar size
+      const width = windowDims.width - x
+
+      const screenshotClip = {
+        x,
+        y: 0,
+        width,
+        height: 220
+      }
+
+
+      await evaluate(async () => {
 
         // Transition to settings page
         const dashboard = document.querySelector('nwb-dashboard')
@@ -159,11 +180,20 @@ describe('E2E Test', () => {
         // Generate test data
         const page = dashboard.page
         page.deleteTestData()
-        return await page.generateTestData()
+      })
+
+      await takeScreenshot('dataset-creation', 300, { clip: screenshotClip })
+
+      const outputLocation = await evaluate(async () => {
+        const dashboard = document.querySelector('nwb-dashboard')
+        const page = dashboard.page
+        const outputLocation = await page.generateTestData()
+        page.requestUpdate()
+        return outputLocation
       })
 
       // Take image after dataset generation
-      await takeScreenshot('dataset-creation', 500)
+      await takeScreenshot('dataset-created', 500, { clip: screenshotClip })
 
       expect(existsSync(outputLocation)).toBe(true)
 
@@ -503,7 +533,7 @@ describe('E2E Test', () => {
     })
 
     test('Ensure there is one completed pipeline', async () => {
-      await takeScreenshot('home-page', 100)
+      await takeScreenshot('home-page-complete', 100)
       const nPipelines = await evaluate(() => document.getElementById('guided-div-resume-progress-cards').children.length)
       expect(nPipelines).toBe(1)
     })