From bd01bd042b2549f6e487ceb16453eaddc05abd9e Mon Sep 17 00:00:00 2001 From: cjsha Date: Mon, 28 Oct 2024 13:14:49 -0400 Subject: [PATCH 1/3] Create preliminary style-guide - Add reference in README just to test how linking to other markdown pages works in github --- README.md | 4 ++++ style-guide.md | 9 +++++++++ 2 files changed, 13 insertions(+) create mode 100644 style-guide.md diff --git a/README.md b/README.md index d781944c..ff20a372 100644 --- a/README.md +++ b/README.md @@ -186,3 +186,7 @@ To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select th #### Bonsai Package Manager Screenshot Edits The layer group consisting of the highlight layer and 1,2,3,4 layers of the screenshots in the bonsai-install\*.xcf or bonsai-update\*.xcf files can be copy and pasted on top of other screenshots. This enables an expedited editing process for creating new edited screenshots. When creating the screenshot, do not change the size of the package manager after opening it. + +## Style Guide + +Refer to the [Style Guide](style-guide.md). \ No newline at end of file diff --git a/style-guide.md b/style-guide.md new file mode 100644 index 00000000..53baeb85 --- /dev/null +++ b/style-guide.md @@ -0,0 +1,9 @@ +# Style Guide + +## Workflows + +Don't use moon button to trigger because it's used to toggle dark/light mode + +## Images/Vvideos + +Moving images/videos should be opt-in. In other words, they shouldn't play by default. From 747e7c69a05ca3d745881bef816700fd806632db Mon Sep 17 00:00:00 2001 From: cjsha Date: Mon, 28 Oct 2024 14:00:53 -0400 Subject: [PATCH 2/3] Preliminary style guide content --- README.md | 12 ------------ style-guide.md | 46 ++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ff20a372..63b9b9f0 100644 --- a/README.md +++ b/README.md @@ -175,18 +175,6 @@ If there are discrepancies between local and remote builds: * Confirm local and remote docfx versions are consistent. This inconsistency can occur when, for example, running `docfx` instead of `dotnet docfx` or running `dotnet tool restore --configfile ` on another config file other than the one in this repo. * Clear any locally cached files that aren't available remotely. Such files exist in the `api` directory (though care to not delete the `.gitignore` in that directory), the `_site` directory, and the workflows directory. Run `./docfx-utils.ps1 -c` to clean artifacts from previous builds. -## Docs Maintainability - -### Creating Edited Screenshots - -There are webpages with edited screenshots of Bonsai. The source material (.xcf GIMP files) belongs in the img-src directory for ease of maintenance. The headers below describe how you can quickly create a new screenshot. - -To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select the `Window` option, and select the window you would like to screenshot. The preference is to take a screenshot against a grey background (e.g. create a (R: 127, G: 127, B: 127) background in GIMP) because some of the background makes it into the screenshot. - -#### Bonsai Package Manager Screenshot Edits - -The layer group consisting of the highlight layer and 1,2,3,4 layers of the screenshots in the bonsai-install\*.xcf or bonsai-update\*.xcf files can be copy and pasted on top of other screenshots. This enables an expedited editing process for creating new edited screenshots. When creating the screenshot, do not change the size of the package manager after opening it. - ## Style Guide Refer to the [Style Guide](style-guide.md). \ No newline at end of file diff --git a/style-guide.md b/style-guide.md index 53baeb85..60026b17 100644 --- a/style-guide.md +++ b/style-guide.md @@ -1,9 +1,47 @@ # Style Guide -## Workflows +## General -Don't use moon button to trigger because it's used to toggle dark/light mode +Follow the style of our other docs sites. -## Images/Vvideos +## Hardware Guide -Moving images/videos should be opt-in. In other words, they shouldn't play by default. +- Don't use moon button to trigger because it's used to toggle dark/light mode. +- Use standard names for saving files: + - specify standard here +- All hardware guides should include loading scripts and ideally example data +- Unify workflows + - Headstage workflows should contain a ConfigureBreakoutBoard node + - Headstage workflows should contain a MemoryMonitor node + +## Real World Visuals + +- Include visuals of real world actions wherever possible. +- Click to play videos and gifs. +- No audio in videos. +- When doing screen records, include visual indicator of mouse clicks and keyboard presses. + - Specify what those indicators look like and how they are done. jonnew likes screen2gif for this. + +## File naming standard + +- Use same abbreviation across files: + - Headstage64: hs64 + - NeuropixelsHeadstage1Ve: np1e + - NeuropixelsHeadstage2Ve: np2e + - NeuropixelsHeadstage2VeBeta: np2ebeta + - Neuropixels 1.0 probes: np1 + - Neuropixels 2.0 probes: np2 + - Neuropixels 2.0 Beta probes: np2beta +- + +## Maintaining screenshots + +### Creating Edited Screenshots + +There are webpages with edited screenshots of Bonsai. The source material (.xcf GIMP files) belongs in the img-src directory for ease of maintenance. The sections below describe how you can quickly create a new screenshot. + +To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select the `Window` option, and select the window you would like to screenshot. The preference is to take a screenshot against a grey background (e.g. create a (R: 127, G: 127, B: 127) background in GIMP) because some of the background makes it into the screenshot. + +### Bonsai Package Manager Screenshot Edits + +The layer group consisting of the highlight layer and 1,2,3,4 layers of the screenshots in the bonsai-install\*.xcf or bonsai-update\*.xcf files can be copy and pasted on top of other screenshots. This enables an expedited editing process for creating new edited screenshots. When creating the screenshot, do not change the size of the package manager after opening it. \ No newline at end of file From 1579ab6ce48a31e8f560cde3c7aa84ccec847a29 Mon Sep 17 00:00:00 2001 From: cjsha Date: Fri, 6 Dec 2024 13:56:32 -0500 Subject: [PATCH 3/3] Add some notes to style guide --- style-guide.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/style-guide.md b/style-guide.md index 60026b17..1e3730d0 100644 --- a/style-guide.md +++ b/style-guide.md @@ -4,6 +4,12 @@ Follow the style of our other docs sites. +## Articles + +- Don't repeat hyperlinks in the same page. +- Try not to overdo formatted text (e.g. a bunch of text wrapped in back ticks can make the page hard to read and look + at) + ## Hardware Guide - Don't use moon button to trigger because it's used to toggle dark/light mode. @@ -38,10 +44,52 @@ Follow the style of our other docs sites. ### Creating Edited Screenshots -There are webpages with edited screenshots of Bonsai. The source material (.xcf GIMP files) belongs in the img-src directory for ease of maintenance. The sections below describe how you can quickly create a new screenshot. +There are webpages with edited screenshots of Bonsai. The source material (.xcf GIMP files) belongs in the img-src +directory for ease of maintenance. The sections below describe how you can quickly create a new screenshot. -To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select the `Window` option, and select the window you would like to screenshot. The preference is to take a screenshot against a grey background (e.g. create a (R: 127, G: 127, B: 127) background in GIMP) because some of the background makes it into the screenshot. +To take the screenshot (in Windows), use the `Windows+Shift+S` hotkey, select the `Window` option, and select the window +you would like to screenshot. The preference is to take a screenshot against a grey background (e.g. create a (R: 127, +G: 127, B: 127) background in GIMP) because some of the background makes it into the screenshot. ### Bonsai Package Manager Screenshot Edits -The layer group consisting of the highlight layer and 1,2,3,4 layers of the screenshots in the bonsai-install\*.xcf or bonsai-update\*.xcf files can be copy and pasted on top of other screenshots. This enables an expedited editing process for creating new edited screenshots. When creating the screenshot, do not change the size of the package manager after opening it. \ No newline at end of file +The layer group consisting of the highlight layer and 1,2,3,4 layers of the screenshots in the bonsai-install\*.xcf or +bonsai-update\*.xcf files can be copy and pasted on top of other screenshots. This enables an expedited editing process +for creating new edited screenshots. When creating the screenshot, do not change the size of the package manager after +opening it. + +## Workflows + +### Example Workflows in Hardware User Guides + +Use "FileCount" for writer operators with a `Suffix` property. This makes loading data easier than using a timestamp +because not all files from a given data acquisition session have the same timestamp. + +Consistency here facilitates scripting the data loading Python scripts. + +All of these example workflows should contain: +- Top-level configuration motif with the headstage/miniscope *and* the breakout board + - Timestamp when the headstage/miniscope is configured + - Write that to CSV + - `Filename`: "start_time_.csv" + - `Selector`: "Timestamp,Value" +- Port status graph + - Timestamp port status changes + - Write to CSV + - `Filename`: "port-status_.csv" + - `Selector`: "Timestamp,Value.Clock,Value.StatusCode" +- Bno055 graph (if relevant) + - Use the correct Bno node (polled or not) + - Write to CSV + - `Filename`: "bno055_.csv" + - `Selector`: "Clock,EulerAngle,Quaternion,Acceleration,Gravity,Temperature" + - Select Quaternion data for commutation + - Connect disabled AutoCommutator node so that people don't need to connect their commutator for the workflow to + run +- Memory monitor graph. + - Select the `PercentUsed` member so the user can monitor memory usage + - Writing to CSV is not necessary (maybe it'ss helpful for them if need to troubleshoot something, but otherwise + irrelevant) + +> [!NOTE] +> Order of selected members (e.g. using the `Selector` property of the `CsvWriter`) matters for loading data.