From 2da58eb6358f2d7dffe4338d05acdb988e157cf7 Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Fri, 27 Oct 2023 14:54:30 +0100 Subject: [PATCH 01/12] Add placeholder page for v1 changes. Add specific brainreg changes page --- .../brainglobe-v1-changelog/brainreg.md | 34 +++++++++++++++++++ .../brainglobe-v1-changelog/overview.md | 6 ++++ 2 files changed, 40 insertions(+) create mode 100644 docs/source/documentation/brainglobe-v1-changelog/brainreg.md create mode 100644 docs/source/documentation/brainglobe-v1-changelog/overview.md diff --git a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md b/docs/source/documentation/brainglobe-v1-changelog/brainreg.md new file mode 100644 index 00000000..d32eebc0 --- /dev/null +++ b/docs/source/documentation/brainglobe-v1-changelog/brainreg.md @@ -0,0 +1,34 @@ +# Version 1: changes to registration and segmentation tools + +Prior to the release of `brainglobe` version 1, there were three tools with the prefix `brainreg` ("brain registration") that were split across three packages. + +- `brainreg` was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence). +- `brainreg-napari` provided a plugin to perform the registration steps interactively through `napari`. It depended on `brainreg` for the core functionality. +- `brainreg-segment` was a companion to `brainreg` that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself. + +With the release of `brainglobe` version 1 and the development of `brainglobe-registration`, the decision was made to disambiguate the role of the segmentation functionality and combine the `napari` plugin with the core functionality. +As a result; `brainreg-segment` has changed name to `brainglobe-segmentation` to emphasise that the segmentation methods are separate from the registration process, and `brainreg` and `brainreg-napari` have been merged. +See below for more details. + +## `brainreg` and `brainreg-napari` + +The previously separate packages `brainreg` and `brainreg-napari` have now been combined into a single package that keeps the `brainreg` name. +This (new) `brainreg` package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) `brainreg` package, and `brainreg.napari` that handles the `napari` widget. +The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the `brainglobe` version 1 package. + +If you were previously using `brainreg` in your scripts and have updated to version 1, you will now need to use `brainreg.core` instead of `brainreg`. +However, the internal structure of the `core` submodule has been retained, so updating your scripts should be a case of replacing "`brainreg`" with "`brainreg.core`" across your codebase. +Similarly, if you were ever importing `brainreg_napari` into your Python scripts, you will need to replace all occurrences of this with `brainreg.napari`. + +If you are installing `brainreg` through `brainglobe` version 1, the `napari` plugin will be automatically included and you won't need to do anything else to install the plugin. +Otherwise, to install the `napari` plugin, you will need to install `brainreg` with it's optional `napari` dependency via + +```bash +python -m pip install brainreg[napari] +``` + +## `brainreg-segment` + +This package has been renamed `brainglobe-segmentation`. +Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously. +However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts. diff --git a/docs/source/documentation/brainglobe-v1-changelog/overview.md b/docs/source/documentation/brainglobe-v1-changelog/overview.md new file mode 100644 index 00000000..7c8771ae --- /dev/null +++ b/docs/source/documentation/brainglobe-v1-changelog/overview.md @@ -0,0 +1,6 @@ +# Brainglobe v1 overview + +This page will contain the user-facing overview of the changes that have been made in the release of brainglobe version 1. + +It will be a high-level summary of the changes to the individual packages, which in turn can link to more detailed pages with information if this is necessary. +It should also include the new install instructions and user-facing organisation. From 4897197c04bb8e0528c5d8df451b025920276c1d Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Fri, 27 Oct 2023 15:35:05 +0100 Subject: [PATCH 02/12] Tidy up standard layout of updates page --- .../documentation/brainglobe-v1-changelog/brainreg.md | 10 ++++++++++ .../documentation/brainglobe-v1-changelog/overview.md | 11 ++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md b/docs/source/documentation/brainglobe-v1-changelog/brainreg.md index d32eebc0..12b91bb3 100644 --- a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md +++ b/docs/source/documentation/brainglobe-v1-changelog/brainreg.md @@ -27,8 +27,18 @@ Otherwise, to install the `napari` plugin, you will need to install `brainreg` w python -m pip install brainreg[napari] ``` +## Command-line executable + +The command-line executable has retained the name `brainreg` and has undergone no usability changes. + +## `napari` plugin + +When loading the plugin in `napari`, you will now find it listed under the plugins menu as "`Atlas Registration (brainreg)`" rather than "`Atlas Registration (brainreg-napari)`". +If you have external scripts that reply on the internal name of the plugin, you will need to update these to `brainreg` (from`brainreg-napari`) accordingly. + ## `brainreg-segment` This package has been renamed `brainglobe-segmentation`. + Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously. However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts. diff --git a/docs/source/documentation/brainglobe-v1-changelog/overview.md b/docs/source/documentation/brainglobe-v1-changelog/overview.md index 7c8771ae..07ea4570 100644 --- a/docs/source/documentation/brainglobe-v1-changelog/overview.md +++ b/docs/source/documentation/brainglobe-v1-changelog/overview.md @@ -1,6 +1,11 @@ # Brainglobe v1 overview -This page will contain the user-facing overview of the changes that have been made in the release of brainglobe version 1. +## Changes at-a-glance -It will be a high-level summary of the changes to the individual packages, which in turn can link to more detailed pages with information if this is necessary. -It should also include the new install instructions and user-facing organisation. +Below is a high-level overview of the changes to the `brainglobe` suite of tools that we offer. +You can follow the links provided for more information; including a listing of relocated and/or renamed tools. + +| Change | | +|--------|:-:| +`brainreg` and `brainreg-napari` have been merged into a single package | [Further info](./brainreg.md) | +`brainreg-segment` has been renamed to `brainglobe-segmentation` | [Further info](./brainreg.md) | From 0a9c18bdf44e69e28c226bd6141eef8a2dac5742 Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Fri, 27 Oct 2023 15:47:54 +0100 Subject: [PATCH 03/12] Consistent code-blocking on website --- .../brainglobe-v1-changelog/brainreg.md | 42 +++++++++++-------- .../brainglobe-v1-changelog/overview.md | 6 +-- 2 files changed, 27 insertions(+), 21 deletions(-) diff --git a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md b/docs/source/documentation/brainglobe-v1-changelog/brainreg.md index 12b91bb3..767cdc33 100644 --- a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md +++ b/docs/source/documentation/brainglobe-v1-changelog/brainreg.md @@ -1,44 +1,50 @@ # Version 1: changes to registration and segmentation tools -Prior to the release of `brainglobe` version 1, there were three tools with the prefix `brainreg` ("brain registration") that were split across three packages. +Prior to the release of brainglobe version 1, there were three tools with the prefix brainreg ("brain registration") that were split across three packages. -- `brainreg` was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence). -- `brainreg-napari` provided a plugin to perform the registration steps interactively through `napari`. It depended on `brainreg` for the core functionality. -- `brainreg-segment` was a companion to `brainreg` that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself. +- brainreg was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence). +- brainreg-napari provided a plugin to perform the registration steps interactively through napari. It depended on brainreg for the core functionality. +- brainreg-segment was a companion to brainreg that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself. -With the release of `brainglobe` version 1 and the development of `brainglobe-registration`, the decision was made to disambiguate the role of the segmentation functionality and combine the `napari` plugin with the core functionality. -As a result; `brainreg-segment` has changed name to `brainglobe-segmentation` to emphasise that the segmentation methods are separate from the registration process, and `brainreg` and `brainreg-napari` have been merged. +With the release of brainglobe version 1 and the development of brainglobe-registration, the decision was made to disambiguate the role of the segmentation functionality and combine the napari plugin with the core functionality. +As a result; brainreg-segment has changed name to brainglobe-segmentation to emphasise that the segmentation methods are separate from the registration process, and brainreg and brainreg-napari have been merged. See below for more details. -## `brainreg` and `brainreg-napari` +## brainreg and brainreg-napari -The previously separate packages `brainreg` and `brainreg-napari` have now been combined into a single package that keeps the `brainreg` name. -This (new) `brainreg` package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) `brainreg` package, and `brainreg.napari` that handles the `napari` widget. -The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the `brainglobe` version 1 package. +The previously separate packages brainreg and brainreg-napari have now been combined into a single package that keeps the brainreg name. +This (new) brainreg package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) brainreg package, and `brainreg.napari` that handles the napari widget. +The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the brainglobe version 1 package. -If you were previously using `brainreg` in your scripts and have updated to version 1, you will now need to use `brainreg.core` instead of `brainreg`. +If you were previously using brainreg in your scripts and have updated to version 1, you will now need to use `brainreg.core` instead of `brainreg`. However, the internal structure of the `core` submodule has been retained, so updating your scripts should be a case of replacing "`brainreg`" with "`brainreg.core`" across your codebase. Similarly, if you were ever importing `brainreg_napari` into your Python scripts, you will need to replace all occurrences of this with `brainreg.napari`. -If you are installing `brainreg` through `brainglobe` version 1, the `napari` plugin will be automatically included and you won't need to do anything else to install the plugin. -Otherwise, to install the `napari` plugin, you will need to install `brainreg` with it's optional `napari` dependency via +If you are installing brainreg as part of the brainglobe version 1 package, the napari plugin will be automatically included and you won't need to do anything else to install the plugin. +Otherwise, to install the napari plugin, you will need to install brainreg with it's optional napari dependency via pip (recommended) ```bash python -m pip install brainreg[napari] ``` +or alternatively via conda + +```bash +conda install brainreg +``` + ## Command-line executable The command-line executable has retained the name `brainreg` and has undergone no usability changes. -## `napari` plugin +## napari plugin -When loading the plugin in `napari`, you will now find it listed under the plugins menu as "`Atlas Registration (brainreg)`" rather than "`Atlas Registration (brainreg-napari)`". -If you have external scripts that reply on the internal name of the plugin, you will need to update these to `brainreg` (from`brainreg-napari`) accordingly. +When loading the plugin in napari, you will now find it listed under the plugins menu as "`Atlas Registration (brainreg)`" rather than "`Atlas Registration (brainreg-napari)`". +If you have external scripts that reply on the internal name of the plugin, you will need to update these to `brainreg` (from `brainreg-napari`) accordingly. -## `brainreg-segment` +## brainreg-segment -This package has been renamed `brainglobe-segmentation`. +This package has been renamed brainglobe-segmentation. Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously. However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts. diff --git a/docs/source/documentation/brainglobe-v1-changelog/overview.md b/docs/source/documentation/brainglobe-v1-changelog/overview.md index 07ea4570..67662cd7 100644 --- a/docs/source/documentation/brainglobe-v1-changelog/overview.md +++ b/docs/source/documentation/brainglobe-v1-changelog/overview.md @@ -2,10 +2,10 @@ ## Changes at-a-glance -Below is a high-level overview of the changes to the `brainglobe` suite of tools that we offer. +Below is a high-level overview of the changes to the brainglobe suite of tools that we offer. You can follow the links provided for more information; including a listing of relocated and/or renamed tools. | Change | | |--------|:-:| -`brainreg` and `brainreg-napari` have been merged into a single package | [Further info](./brainreg.md) | -`brainreg-segment` has been renamed to `brainglobe-segmentation` | [Further info](./brainreg.md) | +brainreg and brainreg-napari have been merged into a single package | [Further info](./brainreg.md) | +brainreg-segment has been renamed to brainglobe-segmentation | [Further info](./brainreg.md) | From dd22991fdc860786b095b9b98fa42a981ed7c555 Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Wed, 1 Nov 2023 11:54:58 +0000 Subject: [PATCH 04/12] Move to releases folder --- .../v1}/brainreg.md | 15 ++++++++++++++- .../v1}/overview.md | 4 ++-- 2 files changed, 16 insertions(+), 3 deletions(-) rename docs/source/{documentation/brainglobe-v1-changelog => releases/v1}/brainreg.md (86%) rename docs/source/{documentation/brainglobe-v1-changelog => releases/v1}/overview.md (78%) diff --git a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md b/docs/source/releases/v1/brainreg.md similarity index 86% rename from docs/source/documentation/brainglobe-v1-changelog/brainreg.md rename to docs/source/releases/v1/brainreg.md index 767cdc33..130fae3a 100644 --- a/docs/source/documentation/brainglobe-v1-changelog/brainreg.md +++ b/docs/source/releases/v1/brainreg.md @@ -45,6 +45,19 @@ If you have external scripts that reply on the internal name of the plugin, you ## brainreg-segment This package has been renamed brainglobe-segmentation. - Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously. However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts. + +If you want to install the package standalone (without using BrainGlobe version 1 or through installing `brainreg`) then we recommend you `pip install` the package into your envrionment: + +```bash +pip install brainglobe-segmentation +``` + +If you have `brainreg-segment` in your environment, you may wish to remove it as it will no longer be needed by `brainreg`: + +```bash +pip uninstall brainreg-segment +``` + +however, `brainreg-segment` is still required by [`cellfinder`](../../documentation/cellfinder/index.md) versions `<=v1.0.0`. diff --git a/docs/source/documentation/brainglobe-v1-changelog/overview.md b/docs/source/releases/v1/overview.md similarity index 78% rename from docs/source/documentation/brainglobe-v1-changelog/overview.md rename to docs/source/releases/v1/overview.md index 67662cd7..52264062 100644 --- a/docs/source/documentation/brainglobe-v1-changelog/overview.md +++ b/docs/source/releases/v1/overview.md @@ -7,5 +7,5 @@ You can follow the links provided for more information; including a listing of r | Change | | |--------|:-:| -brainreg and brainreg-napari have been merged into a single package | [Further info](./brainreg.md) | -brainreg-segment has been renamed to brainglobe-segmentation | [Further info](./brainreg.md) | +brainreg and brainreg-napari have been merged into a single package | [Further info](./brainreg.md#brainreg-and-brainreg-napari) | +brainreg-segment has been renamed to brainglobe-segmentation | [Further info](./brainreg.md#brainreg-segment) | From 1447f8dd773afbb4150c2586d1bff66c4bf1f8c5 Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Wed, 1 Nov 2023 12:24:21 +0000 Subject: [PATCH 05/12] Add brainreg changelog, overview, and full notes --- .../blog/version1/brainreg_update_live.md | 35 +++++++++++++++++++ docs/source/releases/index.md | 9 +++++ docs/source/releases/v1/brainreg.md | 35 +++++++++---------- .../releases/v1/{overview.md => index.md} | 9 +++++ 4 files changed, 69 insertions(+), 19 deletions(-) create mode 100644 docs/source/blog/version1/brainreg_update_live.md create mode 100644 docs/source/releases/index.md rename docs/source/releases/v1/{overview.md => index.md} (88%) diff --git a/docs/source/blog/version1/brainreg_update_live.md b/docs/source/blog/version1/brainreg_update_live.md new file mode 100644 index 00000000..c3a1476e --- /dev/null +++ b/docs/source/blog/version1/brainreg_update_live.md @@ -0,0 +1,35 @@ +--- +blogpost: true +date: Nov 1, 2023 +author: Will Graham +location: London, England +category: BrainGlobe-v1 +language: English +--- + +# Version 1 of `brainreg` and `brainglobe-segmentation` released + +The [restructuring of BrainGlobe](./version_1_announcement.md) is underway, beginning with the release of version 1 of `brainreg` and `brainglobe-segmentation` (previously known as `brainreg-segment`). +Previously, there were three tools with the prefix `brainreg` ("brain registration") that were split across three packages: + +- `brainreg` was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence). +- `brainreg-napari` provided a plugin to perform the registration steps interactively through napari. It depended on `brainreg` for the core functionality. +- `brainreg-segment` was a companion to `brainreg` that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself. + +This release sees `brainreg` come bundled with its napari plugin as an optional package extra, rather than requiring users to install the two packages separately. +Consequentially, `brainreg-napari` has been retired; we recommend you uninstall this package from your environments when you update. +The "combined" `brainreg` is now tagged as `brainreg v1.0.0` and should be considered a stable first release of this tool. + +`brainglobe-segmentation` is the new name of the `brainreg-segment` tool. +With the forthcoming release of BrainGlobe version 1 and the development of `brainglobe-registration`, the decision was made to disambiguate the role of the segmentation functionality and combine the napari plugin with the core functionality. + +## What do I need to do? + +If you were previously using any of the affected tools; you don't need to do anything right now if you want to wait for the full release of BrainGlobe version 1, which will take care of these dependencies for you. +In the time between now and then, the tools as installed will still work but be aware that they will no longer receive updates due to the restructuring. + +If you would like to update your packages now, or would like to know how this will affect your scripts or workflows, [see the full changelog](#full-changelog) which covers API changes and the installation process. + +## Full changelog + +You can find the [full changelog on the releases page](../../releases/v1/brainreg.md). diff --git a/docs/source/releases/index.md b/docs/source/releases/index.md new file mode 100644 index 00000000..6b99aea8 --- /dev/null +++ b/docs/source/releases/index.md @@ -0,0 +1,9 @@ +# Releases + +## BrainGlobe restructuring (version 1) release notes + +```{toctree} +:maxdepth: 2 + +v1/index +``` diff --git a/docs/source/releases/v1/brainreg.md b/docs/source/releases/v1/brainreg.md index 130fae3a..fbec73bb 100644 --- a/docs/source/releases/v1/brainreg.md +++ b/docs/source/releases/v1/brainreg.md @@ -1,27 +1,17 @@ # Version 1: changes to registration and segmentation tools -Prior to the release of brainglobe version 1, there were three tools with the prefix brainreg ("brain registration") that were split across three packages. +## `brainreg` and `brainreg-napari` -- brainreg was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence). -- brainreg-napari provided a plugin to perform the registration steps interactively through napari. It depended on brainreg for the core functionality. -- brainreg-segment was a companion to brainreg that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself. - -With the release of brainglobe version 1 and the development of brainglobe-registration, the decision was made to disambiguate the role of the segmentation functionality and combine the napari plugin with the core functionality. -As a result; brainreg-segment has changed name to brainglobe-segmentation to emphasise that the segmentation methods are separate from the registration process, and brainreg and brainreg-napari have been merged. -See below for more details. - -## brainreg and brainreg-napari - -The previously separate packages brainreg and brainreg-napari have now been combined into a single package that keeps the brainreg name. -This (new) brainreg package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) brainreg package, and `brainreg.napari` that handles the napari widget. -The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the brainglobe version 1 package. +The previously separate packages `brainreg` and `brainreg-napari` have now been combined into a single package that keeps the `brainreg` name. +This (new) `brainreg` package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) `brainreg` package, and `brainreg.napari` that handles the napari widget. +The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the BrainGlobe version 1 package. If you were previously using brainreg in your scripts and have updated to version 1, you will now need to use `brainreg.core` instead of `brainreg`. However, the internal structure of the `core` submodule has been retained, so updating your scripts should be a case of replacing "`brainreg`" with "`brainreg.core`" across your codebase. Similarly, if you were ever importing `brainreg_napari` into your Python scripts, you will need to replace all occurrences of this with `brainreg.napari`. -If you are installing brainreg as part of the brainglobe version 1 package, the napari plugin will be automatically included and you won't need to do anything else to install the plugin. -Otherwise, to install the napari plugin, you will need to install brainreg with it's optional napari dependency via pip (recommended) +If you are installing `brainreg` as part of the brainglobe version 1 package, the napari plugin will be automatically included and you won't need to do anything else to install the plugin. +Otherwise, to install the napari plugin, you will need to install `brainreg` with it's optional napari dependency via pip (recommended) ```bash python -m pip install brainreg[napari] @@ -33,6 +23,13 @@ or alternatively via conda conda install brainreg ``` +After updating, you may want to remove the now deprecated `brainreg-napari` package from your environment if it still persists; + +```bash +pip uninstall brainreg-napari # If you originally installed via pip +conda remove brainreg-napari # If you originally installed via conda +``` + ## Command-line executable The command-line executable has retained the name `brainreg` and has undergone no usability changes. @@ -42,13 +39,13 @@ The command-line executable has retained the name `brainreg` and has undergone n When loading the plugin in napari, you will now find it listed under the plugins menu as "`Atlas Registration (brainreg)`" rather than "`Atlas Registration (brainreg-napari)`". If you have external scripts that reply on the internal name of the plugin, you will need to update these to `brainreg` (from `brainreg-napari`) accordingly. -## brainreg-segment +## `brainreg-segment` -This package has been renamed brainglobe-segmentation. +This package has been renamed `brainglobe-segmentation`. Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously. However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts. -If you want to install the package standalone (without using BrainGlobe version 1 or through installing `brainreg`) then we recommend you `pip install` the package into your envrionment: +If you want to install the package standalone (without using BrainGlobe version 1 or through installing `brainreg`) then we recommend you `pip install` the package into your environment: ```bash pip install brainglobe-segmentation diff --git a/docs/source/releases/v1/overview.md b/docs/source/releases/v1/index.md similarity index 88% rename from docs/source/releases/v1/overview.md rename to docs/source/releases/v1/index.md index 52264062..4cd28275 100644 --- a/docs/source/releases/v1/overview.md +++ b/docs/source/releases/v1/index.md @@ -9,3 +9,12 @@ You can follow the links provided for more information; including a listing of r |--------|:-:| brainreg and brainreg-napari have been merged into a single package | [Further info](./brainreg.md#brainreg-and-brainreg-napari) | brainreg-segment has been renamed to brainglobe-segmentation | [Further info](./brainreg.md#brainreg-segment) | + +## Complete index + +```{toctree} +:maxdepth: 1 +:glob: + +brainreg +``` From d12c29c599603d85ae7256f6480616c5ab036f27 Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Wed, 1 Nov 2023 12:29:33 +0000 Subject: [PATCH 06/12] Make releases page accessible from home --- docs/source/index.md | 9 +++++++++ docs/source/releases/index.md | 2 ++ docs/source/releases/v1/index.md | 2 +- 3 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index d2db870c..d1322d8a 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -39,6 +39,14 @@ How do I get started with these tools? Find out more about these tools. ::: +:::{grid-item-card} {fas}`tags;sd-text-primary` Releases +:img-bottom: _static/atlases.png +:link: releases/index +:link-type: doc + +Release notes and changelogs. +::: + :::: ```{toctree} @@ -48,6 +56,7 @@ Find out more about these tools. about tutorials/index documentation/index +releases/index blog/index more ``` diff --git a/docs/source/releases/index.md b/docs/source/releases/index.md index 6b99aea8..8dd343a5 100644 --- a/docs/source/releases/index.md +++ b/docs/source/releases/index.md @@ -1,5 +1,7 @@ # Releases +Changelogs and release notes for all BrainGlobe tools, all in one place. + ## BrainGlobe restructuring (version 1) release notes ```{toctree} diff --git a/docs/source/releases/v1/index.md b/docs/source/releases/v1/index.md index 4cd28275..74643327 100644 --- a/docs/source/releases/v1/index.md +++ b/docs/source/releases/v1/index.md @@ -1,4 +1,4 @@ -# Brainglobe v1 overview +# BrainGlobe version 1 overview ## Changes at-a-glance From 1384540a1ae94af085877e49f82333fdb70c35a8 Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Wed, 1 Nov 2023 15:33:20 +0000 Subject: [PATCH 07/12] Remove releases card on main page --- docs/source/index.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index d1322d8a..6bbe3928 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -39,14 +39,6 @@ How do I get started with these tools? Find out more about these tools. ::: -:::{grid-item-card} {fas}`tags;sd-text-primary` Releases -:img-bottom: _static/atlases.png -:link: releases/index -:link-type: doc - -Release notes and changelogs. -::: - :::: ```{toctree} From c49240092d4bbf8f60589800abce9d76aeef5eae Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Wed, 1 Nov 2023 15:45:33 +0000 Subject: [PATCH 08/12] Sort blog posts as most recent -> oldest --- docs/source/blog/index.md | 1 - docs/source/index.md | 10 +++------- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/source/blog/index.md b/docs/source/blog/index.md index 5c9e8c15..6ce7389c 100644 --- a/docs/source/blog/index.md +++ b/docs/source/blog/index.md @@ -6,5 +6,4 @@ :date: "%Y-%m-%d" :format: "({date}) {title}, by {author}" :excerpts: -:sort: ``` diff --git a/docs/source/index.md b/docs/source/index.md index 6bbe3928..8669e178 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -4,13 +4,9 @@ The BrainGlobe Initiative exists to facilitate the development of interoperable We have three aims: -* Develop specialist software for specific analysis and visualisation needs, such as -[cellfinder](/documentation/cellfinder/index) and [brainrender](/documentation/brainrender/index). -* Develop core tools to facilitate [others to build interoperable tools in Python](external-tools), e.g., the -[BrainGlobe Atlas API](/documentation/bg-atlasapi/index). -* Build a community of neuroscientists and developers to share knowledge, build software and engage with the -scientific, and open-source community (e.g., by organising hackathons). - +* Develop specialist software for specific analysis and visualisation needs, such as [cellfinder](/documentation/cellfinder/index) and [brainrender](/documentation/brainrender/index). +* Develop core tools to facilitate [others to build interoperable tools in Python](external-tools), e.g., the [BrainGlobe Atlas API](/documentation/bg-atlasapi/index). +* Build a community of neuroscientists and developers to share knowledge, build software and engage with the scientific, and open-source community (e.g., by organising hackathons). ::::{grid} 1 2 2 3 :gutter: 3 From a6672afe74e47f8b8e414ac35e342456cbefffdc Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Wed, 1 Nov 2023 15:47:38 +0000 Subject: [PATCH 09/12] Change announcement link to be relative to generated file structure (prevents redirection when viewing locally) --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 242b6122..5e17ae1f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -107,7 +107,7 @@ ## Cutomize the theme html_theme_options = { - "announcement": "BrainGlobe is undergoing restructuring. Keep track of the latest developments on the blog", + "announcement": "BrainGlobe is undergoing restructuring. Keep track of the latest developments on the blog", "icon_links": [ { # Label for this link From 40030fcaae22350fe5181445c92e57334624964f Mon Sep 17 00:00:00 2001 From: Adam Tyson Date: Wed, 1 Nov 2023 15:53:13 +0000 Subject: [PATCH 10/12] restructure and add community section --- .../{ => community}/developers/conventions.md | 0 docs/source/{ => community}/developers/index.md | 2 +- .../{ => community}/developers/new_releases.md | 0 .../cellfinder-core/cell-detection.md | 0 .../repositories/cellfinder-core/index.md | 0 .../developers/repositories/cellfinder/index.md | 0 docs/source/{ => community}/developers/testing.md | 0 docs/source/{ => community}/developers/tooling.md | 0 docs/source/{ => community}/external-tools.md | 2 +- docs/source/{more.md => community/index.md} | 8 +++++--- docs/source/{ => community}/releases/index.md | 0 .../{ => community}/releases/v1/brainreg.md | 2 +- docs/source/{ => community}/releases/v1/index.md | 4 ++-- docs/source/contact.md | 2 +- .../source/documentation/brainreg/installation.md | 2 +- .../documentation/brainreg/troubleshooting.md | 4 ++-- .../brainreg/user-guide/brainreg-cli.md | 2 +- .../brainreg/user-guide/checking-orientation.md | 2 +- .../documentation/brainrender/installation.md | 2 +- .../documentation/cellfinder/installation.md | 8 ++++---- .../cellfinder/troubleshooting/error-messages.md | 4 ++-- .../cellfinder/troubleshooting/speed-up.md | 4 ++-- .../cellfinder/user-guide/command-line/cli.md | 2 +- .../napari-plugin/training-the-network.md | 2 +- docs/source/documentation/index.md | 9 +-------- .../{general => setting-up}/conda.md | 0 .../documentation/{general => setting-up}/gpu.md | 0 .../{general => setting-up}/image-definition.md | 0 .../images/orientation-asr.webp | Bin .../images/orientation-sal.webp | Bin .../{general => setting-up}/index.md | 2 +- docs/source/index.md | 14 ++++++++------ docs/source/tutorials/brainreg.md | 6 +++--- .../source/tutorials/cellfinder-cli/setting-up.md | 6 +++--- 34 files changed, 43 insertions(+), 46 deletions(-) rename docs/source/{ => community}/developers/conventions.md (100%) rename docs/source/{ => community}/developers/index.md (99%) rename docs/source/{ => community}/developers/new_releases.md (100%) rename docs/source/{ => community}/developers/repositories/cellfinder-core/cell-detection.md (100%) rename docs/source/{ => community}/developers/repositories/cellfinder-core/index.md (100%) rename docs/source/{ => community}/developers/repositories/cellfinder/index.md (100%) rename docs/source/{ => community}/developers/testing.md (100%) rename docs/source/{ => community}/developers/tooling.md (100%) rename docs/source/{ => community}/external-tools.md (97%) rename docs/source/{more.md => community/index.md} (57%) rename docs/source/{ => community}/releases/index.md (100%) rename docs/source/{ => community}/releases/v1/brainreg.md (97%) rename docs/source/{ => community}/releases/v1/index.md (80%) rename docs/source/documentation/{general => setting-up}/conda.md (100%) rename docs/source/documentation/{general => setting-up}/gpu.md (100%) rename docs/source/documentation/{general => setting-up}/image-definition.md (100%) rename docs/source/documentation/{general => setting-up}/images/orientation-asr.webp (100%) rename docs/source/documentation/{general => setting-up}/images/orientation-sal.webp (100%) rename docs/source/documentation/{general => setting-up}/index.md (62%) diff --git a/docs/source/developers/conventions.md b/docs/source/community/developers/conventions.md similarity index 100% rename from docs/source/developers/conventions.md rename to docs/source/community/developers/conventions.md diff --git a/docs/source/developers/index.md b/docs/source/community/developers/index.md similarity index 99% rename from docs/source/developers/index.md rename to docs/source/community/developers/index.md index b7587f28..34b270ca 100644 --- a/docs/source/developers/index.md +++ b/docs/source/community/developers/index.md @@ -5,7 +5,7 @@ **Contributors to BrainGlobe are absolutely encouraged**, whether to fix a bug, develop a new feature, or add a new atlas. There are many BrainGlobe repositories, so it may not be obvious where a new contribution should go. -If you're unsure about any part of the contributing process, please [get in touch](../contact.md). +If you're unsure about any part of the contributing process, please [get in touch](../../contact.md). The best place for questions about contributing is probably the [BrainGlobe Zulip chat](https://brainglobe.zulipchat.com/). diff --git a/docs/source/developers/new_releases.md b/docs/source/community/developers/new_releases.md similarity index 100% rename from docs/source/developers/new_releases.md rename to docs/source/community/developers/new_releases.md diff --git a/docs/source/developers/repositories/cellfinder-core/cell-detection.md b/docs/source/community/developers/repositories/cellfinder-core/cell-detection.md similarity index 100% rename from docs/source/developers/repositories/cellfinder-core/cell-detection.md rename to docs/source/community/developers/repositories/cellfinder-core/cell-detection.md diff --git a/docs/source/developers/repositories/cellfinder-core/index.md b/docs/source/community/developers/repositories/cellfinder-core/index.md similarity index 100% rename from docs/source/developers/repositories/cellfinder-core/index.md rename to docs/source/community/developers/repositories/cellfinder-core/index.md diff --git a/docs/source/developers/repositories/cellfinder/index.md b/docs/source/community/developers/repositories/cellfinder/index.md similarity index 100% rename from docs/source/developers/repositories/cellfinder/index.md rename to docs/source/community/developers/repositories/cellfinder/index.md diff --git a/docs/source/developers/testing.md b/docs/source/community/developers/testing.md similarity index 100% rename from docs/source/developers/testing.md rename to docs/source/community/developers/testing.md diff --git a/docs/source/developers/tooling.md b/docs/source/community/developers/tooling.md similarity index 100% rename from docs/source/developers/tooling.md rename to docs/source/community/developers/tooling.md diff --git a/docs/source/external-tools.md b/docs/source/community/external-tools.md similarity index 97% rename from docs/source/external-tools.md rename to docs/source/community/external-tools.md index 853b4c9b..b3f1aecf 100644 --- a/docs/source/external-tools.md +++ b/docs/source/community/external-tools.md @@ -44,5 +44,5 @@ BrainAtlas wraps the BrainGlobe Atlas API into a package for easy use with the U :::{hint} -if you have developed any software using BrainGlobe tools, please [let us know](contact) and we can advertise it here. +if you have developed any software using BrainGlobe tools, please [let us know](../contact) and we can advertise it here. ::: \ No newline at end of file diff --git a/docs/source/more.md b/docs/source/community/index.md similarity index 57% rename from docs/source/more.md rename to docs/source/community/index.md index 20b438a6..1339ebe3 100644 --- a/docs/source/more.md +++ b/docs/source/community/index.md @@ -1,7 +1,9 @@ -# More +# Community -:::{toctree} +```{toctree} :maxdepth: 1 +developers/index +releases/index external-tools Sample datasets -::: \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/source/releases/index.md b/docs/source/community/releases/index.md similarity index 100% rename from docs/source/releases/index.md rename to docs/source/community/releases/index.md diff --git a/docs/source/releases/v1/brainreg.md b/docs/source/community/releases/v1/brainreg.md similarity index 97% rename from docs/source/releases/v1/brainreg.md rename to docs/source/community/releases/v1/brainreg.md index fbec73bb..47d4b71c 100644 --- a/docs/source/releases/v1/brainreg.md +++ b/docs/source/community/releases/v1/brainreg.md @@ -57,4 +57,4 @@ If you have `brainreg-segment` in your environment, you may wish to remove it as pip uninstall brainreg-segment ``` -however, `brainreg-segment` is still required by [`cellfinder`](../../documentation/cellfinder/index.md) versions `<=v1.0.0`. +however, `brainreg-segment` is still required by [`cellfinder`](../../../documentation/cellfinder/index.md) versions `<=v1.0.0`. diff --git a/docs/source/releases/v1/index.md b/docs/source/community/releases/v1/index.md similarity index 80% rename from docs/source/releases/v1/index.md rename to docs/source/community/releases/v1/index.md index 74643327..cc18b965 100644 --- a/docs/source/releases/v1/index.md +++ b/docs/source/community/releases/v1/index.md @@ -7,8 +7,8 @@ You can follow the links provided for more information; including a listing of r | Change | | |--------|:-:| -brainreg and brainreg-napari have been merged into a single package | [Further info](./brainreg.md#brainreg-and-brainreg-napari) | -brainreg-segment has been renamed to brainglobe-segmentation | [Further info](./brainreg.md#brainreg-segment) | +brainreg and brainreg-napari have been merged into a single package | [Further info](brainreg.md#brainreg-and-brainreg-napari) | +brainreg-segment has been renamed to brainglobe-segmentation | [Further info](brainreg.md#brainreg-segment) | ## Complete index diff --git a/docs/source/contact.md b/docs/source/contact.md index c5c23872..26058ce7 100644 --- a/docs/source/contact.md +++ b/docs/source/contact.md @@ -23,7 +23,7 @@ If you have a feature request, please open an issue at the relevant repository. ## Contributing If you would like to contribute to the BrainGlobe Initiative, please get in touch with us using the [BrainGlobe Zulip chat](https://brainglobe.zulipchat.com/). We always welcome new Pull Requests, -but please take a quick look at the [developer guide](developers/index) first. +but please take a quick look at the [developer guide](community/developers/index) first. ## Other ways to get in touch While we prefer that all discussions about the project are carried out in public, there may be situations in which this diff --git a/docs/source/documentation/brainreg/installation.md b/docs/source/documentation/brainreg/installation.md index c5c3617b..f8fb5924 100644 --- a/docs/source/documentation/brainreg/installation.md +++ b/docs/source/documentation/brainreg/installation.md @@ -35,7 +35,7 @@ If you know what you're doing just run `conda install -c conda-forge brainreg` brainreg is written in Python, and so needs a functional Python installation. Your machine may already have Python installed, but **we recommend installing miniconda**. -**See** [**Using conda**](/documentation/general/conda) **for details.** +**See** [**Using conda**](/documentation/setting-up/conda) **for details.** ```{caution} brainreg should run on any type of Python installation, but if you don't use conda, diff --git a/docs/source/documentation/brainreg/troubleshooting.md b/docs/source/documentation/brainreg/troubleshooting.md index bf8b0aa4..1552d723 100644 --- a/docs/source/documentation/brainreg/troubleshooting.md +++ b/docs/source/documentation/brainreg/troubleshooting.md @@ -7,7 +7,7 @@ NiftyReg, and not directly from brainreg. ## Common problems If brainreg fails to run (rather than runs, but the registration is poor) there are many potential causes. However, the majority of the time, this is due to incorrect parameters passed to brainreg, particularly the [image -orientation and the voxel sizes](/documentation/general/image-definition). Please check these values against your image metadata before running brainreg. +orientation and the voxel sizes](/documentation/setting-up/image-definition). Please check these values against your image metadata before running brainreg. ## Improving registration performance There are many ways to improve registration performance, but this will depend on your data. Some options to try include: @@ -25,4 +25,4 @@ Process failed: ``` This error could be caused by many things, but it is usually due to incorrect [definition of the image orientation or -voxel sizes](/documentation/general/image-definition). Please double-check the values entered are correct. \ No newline at end of file +voxel sizes](/documentation/setting-up/image-definition). Please double-check the values entered are correct. \ No newline at end of file diff --git a/docs/source/documentation/brainreg/user-guide/brainreg-cli.md b/docs/source/documentation/brainreg/user-guide/brainreg-cli.md index 46a53e45..0fdfa730 100644 --- a/docs/source/documentation/brainreg/user-guide/brainreg-cli.md +++ b/docs/source/documentation/brainreg/user-guide/brainreg-cli.md @@ -23,7 +23,7 @@ If you have any spaces in your file-path, please enclose it in quotation marks, * Output directory for all intermediate and final results :::{hint} -You must also specify the orientation and voxel size of your data, see [Image definition](/documentation/general/image-definition). +You must also specify the orientation and voxel size of your data, see [Image definition](/documentation/setting-up/image-definition). ::: ### Additional options diff --git a/docs/source/documentation/brainreg/user-guide/checking-orientation.md b/docs/source/documentation/brainreg/user-guide/checking-orientation.md index 5b5f34a3..ffc8da66 100644 --- a/docs/source/documentation/brainreg/user-guide/checking-orientation.md +++ b/docs/source/documentation/brainreg/user-guide/checking-orientation.md @@ -4,7 +4,7 @@ To ensure that the orientation is set correctly, `napari-brainreg` comes with a orientation (thanks to [Jules Scholler](https://github.com/JulesScholler)!). Once you've loaded your data, fill in the input orientation in the GUI based on the -[bg-space definition](/documentation/general/image-definition) and click `Check orientation`. +[bg-space definition](/documentation/setting-up/image-definition) and click `Check orientation`. This will generate a number of new images that are displayed to the user. The top row of displayed images are the projections of the reference atlas. The bottom row are the projections of the aligned input data. If the two rows are similarly oriented, the orientation is correct. If not, change the orientation and try again. diff --git a/docs/source/documentation/brainrender/installation.md b/docs/source/documentation/brainrender/installation.md index 20c9cd26..04a237ad 100644 --- a/docs/source/documentation/brainrender/installation.md +++ b/docs/source/documentation/brainrender/installation.md @@ -3,7 +3,7 @@ ## Environment To install `brainrender`, you need a python environment with a Python 3.8. This may be a different version than you are -using for other software. Using [conda](/documentation/general/conda) this can be created with: +using for other software. Using [conda](/documentation/setting-up/conda) this can be created with: ```bash conda create --name brainrender python=3.8 -y diff --git a/docs/source/documentation/cellfinder/installation.md b/docs/source/documentation/cellfinder/installation.md index 777abead..f41c01ad 100644 --- a/docs/source/documentation/cellfinder/installation.md +++ b/docs/source/documentation/cellfinder/installation.md @@ -3,7 +3,7 @@ cellfinder should run on most machines, but for routine use on large datasets, you will need a fairly high-powered computer (see the guide to [Speeding up cellfinder](/documentation/cellfinder/troubleshooting/speed-up) for details). -Using an NVIDIA GPU will speed up cell classification considerably. See [setting up your GPU](/documentation/general/gpu) +Using an NVIDIA GPU will speed up cell classification considerably. See [setting up your GPU](/documentation/setting-up/gpu) for details. cellfinder uses brainreg for atlas registration, and the hardware requirements for brainreg depend on the atlas @@ -25,7 +25,7 @@ Most machines (including laptops) will be able to use most of the atlases, but s ## Installing Python Your machine may already have Python -installed, but we recommend installing miniconda. See [Using conda](/documentation/general/conda) for details. +installed, but we recommend installing miniconda. See [Using conda](/documentation/setting-up/conda) for details. ## Installing cellfinder ```{hint} @@ -41,14 +41,14 @@ pip install cellfinder-core :class: dropdown ```{hint} -If you know what you're doing (and [your GPU is set up](/documentation/general/gpu)), just run `pip install cellfinder` +If you know what you're doing (and [your GPU is set up](/documentation/setting-up/gpu)), just run `pip install cellfinder` ``` ## Installing Python cellfinder is written in Python, and so needs a functional Python installation. Your machine may already have Python -installed, but we recommend installing miniconda. See [Using conda](/documentation/general/conda) for details. +installed, but we recommend installing miniconda. See [Using conda](/documentation/setting-up/conda) for details. ```{caution} cellfinder should run on any type of Python installation, but if you don't use conda, diff --git a/docs/source/documentation/cellfinder/troubleshooting/error-messages.md b/docs/source/documentation/cellfinder/troubleshooting/error-messages.md index 288b0ef0..3612c1f0 100644 --- a/docs/source/documentation/cellfinder/troubleshooting/error-messages.md +++ b/docs/source/documentation/cellfinder/troubleshooting/error-messages.md @@ -25,7 +25,7 @@ Otherwise cellfinder will interpret the path as two inputs, separated by a space ### CommandLineInputError: File path: cannot be found. ```bash -imlib.general.exceptions.CommandLineInputError: File path: '/media/adam/Storage/cellfinder.md/data/dataset1' cannot be found. +imlib.setting-up.exceptions.CommandLineInputError: File path: '/media/adam/Storage/cellfinder.md/data/dataset1' cannot be found. ``` If you see an error like this, there could be a few possible reasons, e.g.: @@ -78,7 +78,7 @@ In this case, a previous run of cellfinder hasn't completed. Either wait for it (in the terminal). Alternatively, your version of CUDA and cuDNN may be not compatible with TensorFlow. You can update them by -following the instructions [here](/documentation/general/gpu). +following the instructions [here](/documentation/setting-up/gpu). ### ImportError: DLL load failed: The specified module could not be found. diff --git a/docs/source/documentation/cellfinder/troubleshooting/speed-up.md b/docs/source/documentation/cellfinder/troubleshooting/speed-up.md index 4ae4e24c..7f6fdbca 100644 --- a/docs/source/documentation/cellfinder/troubleshooting/speed-up.md +++ b/docs/source/documentation/cellfinder/troubleshooting/speed-up.md @@ -38,7 +38,7 @@ often work well on modern GPUs with >8GB memory. ::: These steps may be slow if cellfinder is not properly using the GPU. If you have followed the instructions in -[setting up your GPU](/documentation/general/gpu), you may need to check that everything is configured properly: +[setting up your GPU](/documentation/setting-up/gpu), you may need to check that everything is configured properly: Open a terminal (or Anaconda Prompt): @@ -89,6 +89,6 @@ False ``` Then your GPU is not properly configured. If you have followed everything in -[setting up your GPU](/documentation/general/gpu), please go speak to whoever administers your machine. If you're +[setting up your GPU](/documentation/setting-up/gpu), please go speak to whoever administers your machine. If you're still stuck [get in touch](/contact), but there is a limited amount we can do to help configure your system. diff --git a/docs/source/documentation/cellfinder/user-guide/command-line/cli.md b/docs/source/documentation/cellfinder/user-guide/command-line/cli.md index 8d0aea13..f2f8bc5b 100644 --- a/docs/source/documentation/cellfinder/user-guide/command-line/cli.md +++ b/docs/source/documentation/cellfinder/user-guide/command-line/cli.md @@ -23,7 +23,7 @@ the files. **This background channel will be used for all signal channels** :::{caution} You must also specify the orientation and voxel size of your data, see -[Image definition](/documentation/general/image-definition). +[Image definition](/documentation/setting-up/image-definition). ::: ### The following options can also be used: diff --git a/docs/source/documentation/cellfinder/user-guide/napari-plugin/training-the-network.md b/docs/source/documentation/cellfinder/user-guide/napari-plugin/training-the-network.md index 291c5944..6b9debaa 100644 --- a/docs/source/documentation/cellfinder/user-guide/napari-plugin/training-the-network.md +++ b/docs/source/documentation/cellfinder/user-guide/napari-plugin/training-the-network.md @@ -6,7 +6,7 @@ Once napari, and the cellfinder plugin is installed, open napari, and load the p :::{hint} Make sure your GPU is set up to speed up the training. See -[Setting up your GPU](/documentation/general/gpu). +[Setting up your GPU](/documentation/setting-up/gpu). ::: ## Set parameters diff --git a/docs/source/documentation/index.md b/docs/source/documentation/index.md index f9cfaac3..3812e058 100644 --- a/docs/source/documentation/index.md +++ b/docs/source/documentation/index.md @@ -1,15 +1,8 @@ # Documentation -## General -```{toctree} -:maxdepth: 1 -general/index -../developers/index -``` - -## Individual tools ```{toctree} :maxdepth: 1 +setting-up/index bg-atlasapi/index bg-space/index brainreg/index diff --git a/docs/source/documentation/general/conda.md b/docs/source/documentation/setting-up/conda.md similarity index 100% rename from docs/source/documentation/general/conda.md rename to docs/source/documentation/setting-up/conda.md diff --git a/docs/source/documentation/general/gpu.md b/docs/source/documentation/setting-up/gpu.md similarity index 100% rename from docs/source/documentation/general/gpu.md rename to docs/source/documentation/setting-up/gpu.md diff --git a/docs/source/documentation/general/image-definition.md b/docs/source/documentation/setting-up/image-definition.md similarity index 100% rename from docs/source/documentation/general/image-definition.md rename to docs/source/documentation/setting-up/image-definition.md diff --git a/docs/source/documentation/general/images/orientation-asr.webp b/docs/source/documentation/setting-up/images/orientation-asr.webp similarity index 100% rename from docs/source/documentation/general/images/orientation-asr.webp rename to docs/source/documentation/setting-up/images/orientation-asr.webp diff --git a/docs/source/documentation/general/images/orientation-sal.webp b/docs/source/documentation/setting-up/images/orientation-sal.webp similarity index 100% rename from docs/source/documentation/general/images/orientation-sal.webp rename to docs/source/documentation/setting-up/images/orientation-sal.webp diff --git a/docs/source/documentation/general/index.md b/docs/source/documentation/setting-up/index.md similarity index 62% rename from docs/source/documentation/general/index.md rename to docs/source/documentation/setting-up/index.md index 17510033..0d8001c7 100644 --- a/docs/source/documentation/general/index.md +++ b/docs/source/documentation/setting-up/index.md @@ -1,4 +1,4 @@ -# General BrainGlobe documentation +# Setting up ```{toctree} diff --git a/docs/source/index.md b/docs/source/index.md index 8669e178..cd2f6a01 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -4,9 +4,13 @@ The BrainGlobe Initiative exists to facilitate the development of interoperable We have three aims: -* Develop specialist software for specific analysis and visualisation needs, such as [cellfinder](/documentation/cellfinder/index) and [brainrender](/documentation/brainrender/index). -* Develop core tools to facilitate [others to build interoperable tools in Python](external-tools), e.g., the [BrainGlobe Atlas API](/documentation/bg-atlasapi/index). -* Build a community of neuroscientists and developers to share knowledge, build software and engage with the scientific, and open-source community (e.g., by organising hackathons). +* Develop specialist software for specific analysis and visualisation needs, such as +[cellfinder](/documentation/cellfinder/index) and [brainrender](/documentation/brainrender/index). +* Develop core tools to facilitate [others to build interoperable tools in Python](community/external-tools.md), e.g., the +[BrainGlobe Atlas API](/documentation/bg-atlasapi/index). +* Build a community of neuroscientists and developers to share knowledge, build software and engage with the +scientific, and open-source community (e.g., by organising hackathons). + ::::{grid} 1 2 2 3 :gutter: 3 @@ -34,7 +38,6 @@ How do I get started with these tools? Find out more about these tools. ::: - :::: ```{toctree} @@ -44,7 +47,6 @@ Find out more about these tools. about tutorials/index documentation/index -releases/index +community/index blog/index -more ``` diff --git a/docs/source/tutorials/brainreg.md b/docs/source/tutorials/brainreg.md index 6ec4d65c..ec9d4694 100644 --- a/docs/source/tutorials/brainreg.md +++ b/docs/source/tutorials/brainreg.md @@ -13,12 +13,12 @@ To test out brainreg, we supply a small mouse brain dataset to get you started. To run brainreg, you need to know: * Where your data is (in this case, it's the path to the `test_brain` directory) * Where you want to save the output data (we'll just save it into a directory called `brainreg_output`in the same directory as the `test_brain`) -* The pixel sizes of your data in microns (see [Image definition](/documentation/general/image-definition) for details). +* The pixel sizes of your data in microns (see [Image definition](/documentation/setting-up/image-definition) for details). In this case, our data is 40μm per pixel in the coronal plane, and the spacing of the planes is 50μm. * The orientation of your data. The software needs to know how you acquired your data (coronal, sagittal etc.). For this BrainGlobe uses [bg-space](/documentation/bg-space/index). For this tutorial, the orientation is `psl`, which means that the data origin is the most **p**osterior, **s**uperior, **l**eft voxel. For more details see -[Image definition](/documentation/general/image-definition) +[Image definition](/documentation/setting-up/image-definition) * Which atlas you want to use (the list of available atlases is available [here](/documentation/bg-atlasapi/usage/atlas-details)). In this case, we want to use a mouse atlas (as that's what our data is), and we'll use the 50μm version of the [Allen Mouse Brain Atlas](https://mouse.brain-map.org/static/atlas) @@ -86,7 +86,7 @@ Toggling the visibility of the `Boundaries` layer (click the eye icon) is the ea ### Setting up * Open a terminal (Linux/macOS) or your command prompt (Windows) -* Activate your [conda environment](/documentation/general/conda) +* Activate your [conda environment](/documentation/setting-up/conda) ### Run brainreg To run brainreg, you need to pass: diff --git a/docs/source/tutorials/cellfinder-cli/setting-up.md b/docs/source/tutorials/cellfinder-cli/setting-up.md index 37008711..51b48c23 100644 --- a/docs/source/tutorials/cellfinder-cli/setting-up.md +++ b/docs/source/tutorials/cellfinder-cli/setting-up.md @@ -9,7 +9,7 @@ `test_brain` with two directories, each containing 2800 images * Open a terminal (Linux) or your command prompt (Windows) * Navigate to the directory containing the `test_brain` directory (e.g. using `cd`) -* Activate your [conda environment ](/documentation/general/conda) +* Activate your [conda environment ](/documentation/setting-up/conda) :::{hint} The test data supplied is purposefully not the "best". It has a low SNR, and some artefacts such as fluorescent @@ -33,12 +33,12 @@ autofluorescence channel. In this case, `test_brain/ch00` is the signal channel autofluroescence channel * Where you want to save the output data (we'll just save it into a directory called `cellfinder_output`in the same directory as the `test_brain`) -* The pixel sizes of your data in microns (see [Image definition](/documentation/general/image-definition) for details). +* The pixel sizes of your data in microns (see [Image definition](/documentation/setting-up/image-definition) for details). In this case, our data is 2μm per pixel in the coronal plane and the spacing of each plane is 5μm * The orientation of your data. For atlas registration (using [brainreg](/documentation/brainreg/index)) the software needs to know how you acquired your data (coronal, sagittal etc.). For this cellfinder uses [bg-space](/documentation/bg-space/index). Full details on how to enter your data orientation can also be -found in the [Image definition](/documentation/general/image-definition) section. For this tutorial, the orientation +found in the [Image definition](/documentation/setting-up/image-definition) section. For this tutorial, the orientation is `psl`, which means that the data origin is the most **p**osterior, **s**uperior, **l**eft voxel. * Which atlas you want to use (you can see which are available by running `brainglobe list`. In this case, we want to use a mouse atlas (as that's what our data is), and we'll use the 10μm version of the From 291a4d13537aa4a67e40fef93ec9c74fcc61e3ae Mon Sep 17 00:00:00 2001 From: Adam Tyson Date: Wed, 1 Nov 2023 16:55:36 +0000 Subject: [PATCH 11/12] Correct erroneous find & replace --- .../documentation/cellfinder/troubleshooting/error-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/documentation/cellfinder/troubleshooting/error-messages.md b/docs/source/documentation/cellfinder/troubleshooting/error-messages.md index 3612c1f0..290700b6 100644 --- a/docs/source/documentation/cellfinder/troubleshooting/error-messages.md +++ b/docs/source/documentation/cellfinder/troubleshooting/error-messages.md @@ -25,7 +25,7 @@ Otherwise cellfinder will interpret the path as two inputs, separated by a space ### CommandLineInputError: File path: cannot be found. ```bash -imlib.setting-up.exceptions.CommandLineInputError: File path: '/media/adam/Storage/cellfinder.md/data/dataset1' cannot be found. +imlib.general.exceptions.CommandLineInputError: File path: '/media/adam/Storage/cellfinder.md/data/dataset1' cannot be found. ``` If you see an error like this, there could be a few possible reasons, e.g.: From c89f72d9eb79aeee59feb87aaee514cd6f0c611d Mon Sep 17 00:00:00 2001 From: willGraham01 <1willgraham@gmail.com> Date: Mon, 6 Nov 2023 10:19:24 +0000 Subject: [PATCH 12/12] Fix X-references after file relocation --- docs/source/blog/version1/brainreg_update_live.md | 2 +- docs/source/tutorials/tutorial-whole-brain-registration.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/blog/version1/brainreg_update_live.md b/docs/source/blog/version1/brainreg_update_live.md index c3a1476e..f144a836 100644 --- a/docs/source/blog/version1/brainreg_update_live.md +++ b/docs/source/blog/version1/brainreg_update_live.md @@ -32,4 +32,4 @@ If you would like to update your packages now, or would like to know how this wi ## Full changelog -You can find the [full changelog on the releases page](../../releases/v1/brainreg.md). +You can find the [full changelog on the releases page](../../community/releases/v1/brainreg.md). diff --git a/docs/source/tutorials/tutorial-whole-brain-registration.md b/docs/source/tutorials/tutorial-whole-brain-registration.md index 08ae5a61..180d3a29 100644 --- a/docs/source/tutorials/tutorial-whole-brain-registration.md +++ b/docs/source/tutorials/tutorial-whole-brain-registration.md @@ -1,6 +1,6 @@ # Registering a whole-brain image to an atlas -In this tutorial, you will use the [brainreg](/documentation/brainreg) plugin for [napari](https://napari.org) to +In this tutorial, you will use the [brainreg](../documentation/brainreg/index.md) plugin for [napari](https://napari.org) to register (align) a whole-mouse brain image to a reference atlas. The focus of this tutorial is simply to successfully register a single image. @@ -45,7 +45,7 @@ visibility and contrast of the loaded data. **Registration results overlaid onto raw data.** 9. At this point, registration is complete. A number of -[files are created in the output directory](documentation/brainreg/user-guide/output-files) that can be used for +[files are created in the output directory](../documentation/brainreg/user-guide/output-files.md) that can be used for downstream analysis. :::{note}