Merge pull request #8 from kabilar/main

Update readme and docs for first docs release
datajoint · Apr 21, 2023 · 2da8ae3 · 2da8ae3
2 parents 1f8ef10 + 52fb75f
commit 2da8ae3
Show file tree

Hide file tree

Showing 18 changed files with 166 additions and 157 deletions.
diff --git a/.github/workflows/u24_element_release_call.yaml b/.github/workflows/u24_element_release_call.yaml
@@ -17,7 +17,6 @@ jobs:
     secrets:
       TWINE_USERNAME: ${{secrets.TWINE_TEST_USERNAME}}
       TWINE_PASSWORD: ${{secrets.TWINE_TEST_PASSWORD}}
-      GOOGLE_ANALYTICS_KEY: ${{secrets.GOOGLE_ANALYTICS_KEY}}
   call_u24_elements_release_alpine:
     if: >-
       github.event.workflow_run.conclusion == 'success' && github.repository_owner == 'datajoint' && !contains(github.event.workflow_run.head_branch, 'test')
@@ -27,4 +26,3 @@ jobs:
     secrets:
       TWINE_USERNAME: ${{secrets.TWINE_USERNAME}}
       TWINE_PASSWORD: ${{secrets.TWINE_PASSWORD}}
-      GOOGLE_ANALYTICS_KEY: ${{secrets.GOOGLE_ANALYTICS_KEY}}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,8 +3,14 @@
 Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
 
+## [0.1.1] - 2023-04-19
+
++ Update - Docs by adding `Data Pipeline`, `Key Partnerships`, and `Roadmap` pages
++ Update - README with links to tutorials and docs
+
 ## [0.1.0] - 2022-12-19
 
 + Add - Table structure and basic docs (changelog, contribution guidelines, etc.)
 
+[0.1.1](https://github.com/datajoint/element-optogenetics/releases/tag/0.1.1)
 [0.1.0](https://github.com/datajoint/element-optogenetics/releases/tag/0.1.0)
diff --git a/README.md b/README.md
@@ -1,11 +1,27 @@
 # DataJoint Element - Optogenetics
 
-DataJoint Element for managing data from optogenetics experiments. DataJoint Elements collectively standardize
-and automate data collection and analysis for neuroscience experiments.  Each Element is
-a modular pipeline for data storage and processing with corresponding database
-tables that can be combined with other Elements to assemble a fully functional pipeline.
+DataJoint Element for managing data from optogenetics experiments. DataJoint Elements 
+collectively standardize and automate data collection and analysis for neuroscience 
+experiments.  Each Element is a modular pipeline for data storage and processing with 
+corresponding database tables that can be combined with other Elements to assemble a 
+fully functional pipeline.
 
-![diagram](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/diagram_flowchart.svg)
+## Experiment Flowchart
 
-Installation and usage instructions can be found at the
-[Element documentation](httpws://datajoint.com/docs/elements/element-optogenetics).
+![flowchart](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/flowchart.svg)
+
+## Data Pipeline
+
+![pipeline](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/pipeline.svg)
+
+## Getting Started
+
++ Install from PyPI
+
+     ```bash
+     pip install element-optogenetics
+     ```
+
++ [Interactive tutorial on GitHub Codespaces](https://github.com/datajoint/workflow-optogenetics#interactive-tutorial)
+
++ [Documentation](https://datajoint.com/docs/elements/element-optogenetics)
diff --git a/docs/docker-compose.yaml b/docs/docker-compose.yaml
@@ -14,7 +14,6 @@ services:
       - PACKAGE
       - UPSTREAM_REPO
       - MODE
-      - GOOGLE_ANALYTICS_KEY
       - PATCH_VERSION
     volumes:
       - ../docs:/main/docs

diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml
@@ -6,21 +6,22 @@ repo_url: https://github.com/datajoint/element-optogenetics
 repo_name: datajoint/element-optogenetics
 nav:
   - Element Optogenetics: index.md
+  - Data Pipeline: pipeline.md
+  - Tutorials:
+      - tutorials/index.md
+      - Notebook: tutorials/tutorial.ipynb
   - Concepts: concepts.md
-  - Tutorials: 
-    - Overview: tutorials/index.md
-    - Configure: tutorials/01-configure.ipynb
-    - Workflow Structure: tutorials/02-workflow-structure-optional.ipynb
-    - Process: tutorials/03-process.ipynb
+  - Key Partnerships: partnerships.md
+  - Roadmap: roadmap.md
   - Citation: citation.md
   - API: api/ # defer to gen-files + literate-nav
   - Changelog: changelog.md
 
 # --------------------- NOTES TO CONTRIBUTORS -----------------------
 # Markdown in mkdocs
-# 01. Redering concatenates across single line breaks. This means...
+# 01. Rendering concatenates across single line breaks. This means...
 #     A. We have to be careful to add extra line breaks around paragraphs,
-#        including between the end of a pgf and the beginnign of bullets.
+#        including between the end of a pgf and the beginning of bullets.
 #     B. We can use hard wrapping to make github reviews easier to read.
 #        VSCode Rewrap extension offers a keyboard shortcut for hard wrap
 #        at the ruler, but don't add breaks in [multiword links](example.com)
@@ -46,17 +47,14 @@ nav:
 #     UPSTREAM_REPO=https://github.com/datajoint/element-{ELEMENT}.git \
 #     HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
 #     ```
-# 02. Site analytics depend on a local environment variable GOOGLE_ANALYTICS_KEY
-#     You can find this in LastPass or declare with any string to suprress errors
-# 03. The API section will pull docstrings.
-#     A. Follow google styleguide e.g., 
+# 02. The API section will pull docstrings.
+#     A. Follow google style guide e.g., 
 #        https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
 #        With typing suggestions: https://docs.python.org/3/library/typing.html
 #     B. To pull a specific workflow fork, change ./docs/src/api/make_pages.py#L19
-# 04. To see your fork of the workflow-{element} in this render, change the
+# 03. To see your fork of the workflow-{element} in this render, change the
 #     URL in ./docs/src/api/make_pages.py#L19 to your fork.
-# 05. For redirecting options For redirect options, see 'redirects' below.
-# 06. To deploy this site on your fork, 
+# 04. To deploy this site on your fork, 
 #     A. declare a branch called gh-pages
 #     B. go to the your fork > settings > pages 
 #     C. direct pages to render from the gh-pages branch at root
@@ -92,9 +90,6 @@ theme:
 plugins:
   - markdownextradata: {}
   - search
-  # - redirects: # OPTIONAL REDIRECTS
-  #     redirect_maps:
-  #       "index.md": "getting_started.md"
   - mkdocstrings:
       default_handler: python
       handlers:
@@ -136,13 +131,12 @@ markdown_extensions:
   - footnotes
   - pymdownx.inlinehilite
   - pymdownx.snippets
-
+  - pymdownx.magiclink # Displays bare URLs as links
+  - pymdownx.tasklist: # Renders check boxes in tasks lists
+      custom_checkbox: true
 extra:
   PATCH_VERSION: !ENV PATCH_VERSION
   generator: false # Disable watermark
-  analytics:
-    provider: google
-    property: !ENV GOOGLE_ANALYTICS_KEY
   version:
     provider: mike
   social:

diff --git a/docs/src/.overrides/assets/stylesheets/extra.css b/docs/src/.overrides/assets/stylesheets/extra.css
@@ -90,4 +90,8 @@ html a[title="YouTube"].md-social__link svg {
     /* footer */
     /* previous/next text */
     /* --md-footer-fg-color: var(--dj-white); */
-}
+}
+
+[data-md-color-scheme="slate"] .jupyter-wrapper .Table Td {
+    color: var(--dj-black)
+}
diff --git a/docs/src/citation.md b/docs/src/citation.md
@@ -8,6 +8,5 @@ Resource Identifier (RRID).
   Reimer J, Walker EY, Tolias AS. DataJoint Elements: Data Workflows for
   Neurophysiology. bioRxiv. 2021 Jan 1. doi: https://doi.org/10.1101/2021.03.30.437358
 
-- DataJoint Elements ([RRID:SCR_021894](https://scicrunch.org/resolver/SCR_021894)) -
-  Element Optogenetics (version {{ PATCH_VERSION }})
-
+- DataJoint Element Optogenetics - [RRID:SCR_021894](https://scicrunch.org/resolver/SCR_021894) - Version {{ PATCH_VERSION }}
+
diff --git a/docs/src/concepts.md b/docs/src/concepts.md
@@ -12,74 +12,3 @@ causal links between the activity of neuronal populations and corresponding anim
 [^1]: Boyden, E. S., Zhang, F., Bamberg, E., Nagel, G., & Deisseroth, K. (2005).
     [Millisecond-timescale, genetically targeted optical control of neural activity](https://www.nature.com/articles/nn1525).
     Nature neuroscience, 8(9), 1263-1268.
-
-## Key Partnerships
-
-Key members of the [U19 BrainCoGS project](https://www.braincogs.org/) at Princeton
-University were consulted during development. The
-[U19 BrainCoGS MATLAB pipeline](https://github.com/BrainCOGS/U19-pipeline-matlab/tree/master/schemas/%2Boptogenetics)
-serves as an important precursor project to this Element.
-
-## Element Features
-
-This Element stores key information about optogenetic stimulus protocols used during experimental sessions:
-- Stimulus parameters (waveform properties, wavelength, power, duration, etc.)
-- Implant location of the optical fiber.
-- Stimulus pulse generator.
-- Stimulus start and end times during an experimental session.
-
-## Element Architecture
-
-Each node in the following diagram represents the analysis code in the workflow and the
-corresponding tables in the database.  Within the workflow, Element Optogenetics connects
-to upstream Elements including Lab, Animal, and Session.  For more detailed
-documentation on each table, see the API docs for the respective schemas.
-
-![element-optogenetics diagram](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/diagram_opto.svg)
-
-### `reference` schema ([API docs](../api/workflow_Optogenetics/pipeline/#workflow_Optogenetics.reference.Device))
-
-| Table | Description |
-| --- | --- |
-| Device | Pulse generator device |
-
-### `subject` schema ([API docs](https://datajoint.com/docs/elements/element-animal/latest/api/element_animal/subject/#element_animal.subject.Subject))
-
-- Although not required, most choose to connect the `Session` table to a `Subject` table.
-
-| Table | Description |
-| --- | --- |
-| Subject | Basic information of the research subject |
-
-### `surgery` schema ([API docs](https://datajoint.com/docs/elements/element-animal/latest/api/element_animal/surgery/#element_animal.surgery.Implantation))
-
-- The `Implantation` table can be user-defined , or one can choose to use the `surgery.Implantation` table from `element-animal`.
-
-| Table | Description |
-| --- | --- |
-| Implantation | Location of an implanted device |
-
-### `session` schema ([API docs](https://datajoint.com/docs/elements/element-session/latest/api/element_session/session_with_id))
-
-| Table | Description |
-| --- | --- |
-| Session | Unique experimental session identifier |
-
-### `optogenetics` schema ([API docs](../api/element_optogenetics/optogenetics))
-
-| Table               | Description |
-| ---                 |   ---       |
-| OptoWaveformType | Stimulus waveform type (e.g., square, ramp, sine) |
-| OptoWaveform | Shape of one cycle of the stimulus waveform |
-| OptoWaveform.Square | Square waveform properties |
-| OptoWaveform.Ramp | Ramp waveform properties |
-| OptoWaveform.Sine | Sine waveform properties |
-| OptoStimParams | Stimulus parameters |
-| OptoProtocol | Protocol for a given session |
-| OptoEvent | Start and end time of the stimulus within a session |
-
-## Roadmap
-
-Further development of this Element is community driven.  Upon user requests and based
-on guidance from the Scientific Steering Group we will add further features to this
-Element.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,12 +1,29 @@
 # Element Optogenetics
 
-DataJoint Element for managing data from optogenetics experiments. DataJoint Elements collectively standardize
-and automate data collection and analysis for neuroscience experiments.  Each Element is
-a modular pipeline for data storage and processing with corresponding database
-tables that can be combined with other Elements to assemble a fully functional pipeline.
+DataJoint Element for managing data from optogenetics experiments. DataJoint Elements 
+collectively standardize and automate data collection and analysis for neuroscience 
+experiments.  Each Element is a modular pipeline for data storage and processing with 
+corresponding database tables that can be combined with other Elements to assemble a 
+fully functional pipeline.
 
-![diagram](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/diagram_flowchart.svg)
+## Experiment Flowchart
 
-Visit the [Concepts page](./concepts.md) for more information on optogenetics research
-and Element Optogenetics.  To get started with building your data pipeline visit the
-[Tutorials page](./tutorials/index.md).
+![flowchart](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/flowchart.svg)
+
+## Data Pipeline
+
+![pipeline](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/pipeline.svg)
+
+## Getting Started
+
++ Install from PyPI
+
+     ```bash
+     pip install element-optogenetics
+     ```
+
++ [Data Pipeline](./pipeline.md) - Pipeline and table descriptions
+
++ [Tutorials](./tutorials/index.md) - Start building your data pipeline
+
++ [Code Repository](https://github.com/datajoint/element-optogenetics/){:target="_blank"}
diff --git a/docs/src/partnerships.md b/docs/src/partnerships.md
@@ -0,0 +1,6 @@
+# Key Partnerships
+
+Key members of the [U19 BrainCoGS project](https://www.braincogs.org/) at Princeton
+University were consulted during development. The
+[U19 BrainCoGS MATLAB pipeline](https://github.com/BrainCOGS/U19-pipeline-matlab/tree/master/schemas/%2Boptogenetics)
+serves as an important precursor project to this Element.
diff --git a/docs/src/pipeline.md b/docs/src/pipeline.md
@@ -0,0 +1,49 @@
+# Data Pipeline
+
+Each node in the following diagram represents the analysis code in the workflow and the
+corresponding tables in the database.  Within the workflow, Element Optogenetics connects
+to upstream Elements including Lab, Animal, and Session.  For more detailed
+documentation on each table, see the API docs for the respective schemas.
+
+![pipeline](https://raw.githubusercontent.com/datajoint/element-optogenetics/main/images/pipeline.svg)
+
+## `reference` schema ([API docs](../api/workflow_Optogenetics/pipeline/#workflow_Optogenetics.reference.Device))
+
+| Table | Description |
+| --- | --- |
+| Device | Pulse generator device |
+
+## `subject` schema ([API docs](https://datajoint.com/docs/elements/element-animal/latest/api/element_animal/subject/#element_animal.subject.Subject))
+
+- Although not required, most choose to connect the `Session` table to a `Subject` table.
+
+| Table | Description |
+| --- | --- |
+| Subject | Basic information of the research subject |
+
+## `surgery` schema ([API docs](https://datajoint.com/docs/elements/element-animal/latest/api/element_animal/surgery/#element_animal.surgery.Implantation))
+
+- The `Implantation` table can be user-defined , or one can choose to use the `surgery.Implantation` table from `element-animal`.
+
+| Table | Description |
+| --- | --- |
+| Implantation | Location of an implanted device |
+
+## `session` schema ([API docs](https://datajoint.com/docs/elements/element-session/latest/api/element_session/session_with_id))
+
+| Table | Description |
+| --- | --- |
+| Session | Unique experimental session identifier |
+
+## `optogenetics` schema ([API docs](../api/element_optogenetics/optogenetics))
+
+| Table               | Description |
+| ---                 |   ---       |
+| OptoWaveformType | Stimulus waveform type (e.g., square, ramp, sine) |
+| OptoWaveform | Shape of one cycle of the stimulus waveform |
+| OptoWaveform.Square | Square waveform properties |
+| OptoWaveform.Ramp | Ramp waveform properties |
+| OptoWaveform.Sine | Sine waveform properties |
+| OptoStimParams | Stimulus parameters |
+| OptoProtocol | Protocol for a given session |
+| OptoEvent | Start and end time of the stimulus within a session |
diff --git a/docs/src/roadmap.md b/docs/src/roadmap.md
@@ -0,0 +1,13 @@
+# Roadmap
+
+This Element stores key information about optogenetic stimulus protocols used during 
+experimental sessions.
+
+- [x] Stimulus parameters (waveform properties, wavelength, power, duration, etc.)
+- [x] Implant location of the optical fiber
+- [x] Stimulus pulse generator
+- [x] Stimulus start and end times during an experimental session
+
+Further development of this Element is community driven.  Upon user requests and based 
+on guidance from the Scientific Steering Group we will add further features to this 
+Element.
diff --git a/docs/src/tutorials/index.md b/docs/src/tutorials/index.md
@@ -1,33 +1,14 @@
 # Tutorials
 
-## Installation
++ DataJoint Elements are modular pipelines that can be connected into a complete workflow.  [Workflow Optogenetics](https://github.com/datajoint/workflow-optogenetics)) is an example that combines four DataJoint Elements - Lab, Animal, Session, and Optogenetics.
 
-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 workflows
-(e.g., [workflow-optogenetics](https://github.com/datajoint/workflow-optogenetics)), 
-which can be modified for a user's specific experimental requirements.  This example
-workflow uses four Elements (Lab, Animal, Session, and Optogenetics) to construct a
-complete pipeline, and is able to ingest experimental metadata.
++ Workflow Optogenetics includes an [interactive tutorial on GitHub Codespaces](https://github.com/datajoint/workflow-optogenetics#interactive-tutorial), which is configured for users to run the pipeline.
 
-<!-- ### Videos
++ In the interactive tutorial, the [example notebook](https://github.com/datajoint/workflow-optogenetics/tree/main/notebooks.tutorial.ipynb) describes the pipeline and provides instructions for adding data to the pipeline.
 
-The [Element Optogenetics tutorial](https://www.youtube.com/watch?v=8FDjTuQ52gQ) gives an 
-overview of the workflow files and notebooks as well as core concepts related to 
-optogenetics research.
+## Installation Instructions for Active Projects
 
-[![YouTube tutorial](https://img.youtube.com/vi/8FDjTuQ52gQ/0.jpg)](https://www.youtube.com/watch?v=8FDjTuQ52gQ) -->
++ The Workflow Optogenetics described above can be modified for a user's specific experimental requirements and thereby used in active projects.  
 
-### Notebooks
-
-Each of the 
-[notebooks](https://github.com/datajoint/workflow-optogenetics/tree/main/notebooks) in 
-the workflow steps through ways to interact with the Element itself. 
-
-- [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.
++ The GitHub Codespace and Dev Container is configured for tutorials and prototyping.  
+We recommend users to configure a database specifically for production pipelines.  Instructions for a local installation of the integrated development environment with a database can be found on the [User Guide](https://datajoint.com/docs/elements/user-guide/) page.