From 64467d4b6a4719309607699415cee2edd72c70f4 Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Mon, 30 Oct 2023 10:59:38 +0000
Subject: [PATCH 01/10] Add ABlog to docs and build
---
docs/requirements.txt | 1 +
docs/source/conf.py | 11 ++++++-----
2 files changed, 7 insertions(+), 5 deletions(-)
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 4e0b92bc..2311d2a4 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -8,3 +8,4 @@ sphinx-design
sphinx-togglebutton
sphinx-notfound-page
sphinx-sitemap
+ablog>=0.11.0rc2
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 10e30840..9f5f06b9 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -31,6 +31,7 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ "ablog",
"sphinx.ext.githubpages",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
@@ -43,7 +44,7 @@
"myst_parser",
"numpydoc",
"nbsphinx",
- "notfound.extension"
+ "notfound.extension",
]
# Configure the myst parser to enable cool markdown features
@@ -142,7 +143,7 @@
"icon": "fa-solid fa-question",
# The type of image to be used (see below for details)
"type": "fontawesome",
- }
+ },
],
"logo": {
"text": "BrainGlobe",
@@ -158,7 +159,7 @@
html_show_sourcelink = False
notfound_context = {
- 'body': "This page has likely moved.
We have recently restructured the BrainGlobe website, and some links have broken. Try using the search box or go to the homepage. If you can'
",
+ "body": "This page has likely moved.
We have recently restructured the BrainGlobe website, and some links have broken. Try using the search box or go to the homepage. If you can'
",
}
notfound_context = {
@@ -171,8 +172,8 @@
We have recently restructured the BrainGlobe website, and some links have broken. Try using the search box or go to the homepage.
If you can't find the information you need. Please get in touch.
-"""
+""",
}
# needed for GH pages (vs readthedocs)
-notfound_urls_prefix = None
\ No newline at end of file
+notfound_urls_prefix = None
From 91a6386a10c4c601e29e27d9c10b9b19bc096537 Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Mon, 30 Oct 2023 11:29:40 +0000
Subject: [PATCH 02/10] Add blogs folder and to toctree
---
docs/source/blog/index.md | 15 +++++++++++++++
.../source/blog/version1/version_1_annoucement.md | 12 ++++++++++++
docs/source/index.md | 1 +
3 files changed, 28 insertions(+)
create mode 100644 docs/source/blog/index.md
create mode 100644 docs/source/blog/version1/version_1_annoucement.md
diff --git a/docs/source/blog/index.md b/docs/source/blog/index.md
new file mode 100644
index 00000000..29957126
--- /dev/null
+++ b/docs/source/blog/index.md
@@ -0,0 +1,15 @@
+# Blog
+
+## BrainGlobe version 1
+
+All announcements containing information on the progress of the release of BrainGlobe v1.
+Check here for changelogs and package updates as they are released.
+
+```{postlist}
+:list-style: circle
+:category: BrainGlobe-v1
+:date: "%Y-%m-%d"
+:format: "{date} - {title}"
+:excerpts:
+:sort:
+```
diff --git a/docs/source/blog/version1/version_1_annoucement.md b/docs/source/blog/version1/version_1_annoucement.md
new file mode 100644
index 00000000..31dccfcb
--- /dev/null
+++ b/docs/source/blog/version1/version_1_annoucement.md
@@ -0,0 +1,12 @@
+---
+blogpost: true
+date: Oct 30, 2023
+author: Will Graham
+location: London, England
+category: BrainGlobe-v1
+language: English
+---
+
+# BrainGlobe version 1 is coming
+
+Foobar
\ No newline at end of file
diff --git a/docs/source/index.md b/docs/source/index.md
index 717efc69..d2db870c 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -48,5 +48,6 @@ Find out more about these tools.
about
tutorials/index
documentation/index
+blog/index
more
```
From 18b7caeb9e16afa1a4850987daae9ac3d8eca682 Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Mon, 30 Oct 2023 12:28:21 +0000
Subject: [PATCH 03/10] A draft blog post
---
.../blog/version1/version_1_annoucement.md | 41 ++++++++++++++++++-
1 file changed, 40 insertions(+), 1 deletion(-)
diff --git a/docs/source/blog/version1/version_1_annoucement.md b/docs/source/blog/version1/version_1_annoucement.md
index 31dccfcb..c259c2e4 100644
--- a/docs/source/blog/version1/version_1_annoucement.md
+++ b/docs/source/blog/version1/version_1_annoucement.md
@@ -9,4 +9,43 @@ language: English
# BrainGlobe version 1 is coming
-Foobar
\ No newline at end of file
+BrainGlobe provides and maintains a number of open-source tools, each of which are provided as Python-based software packages.
+A number of these tools also come with a user-interface provided by a [napari plugin](https://napari.org/) that can be installed on top of the basic tool package.
+Whilst there is an advantage to the modularity provided by maintaining separate tools, the same modularity can present challenges and unnecessary difficulties when running an analysis that relies on multiple BrainGlobe tools.
+Particular pinch points include:
+
+- Needing to manually install each tool (and its napari plugin in some cases) that needs to be used one-at-a-time.
+- Propagation of legacy naming conventions, as tools have evolved and their purpose has been redefined.
+- Complex dependency trees, further complicated by optional dependencies.
+
+To address these issues, we are pleased to announce that development on "BrainGlobe version 1" is underway.
+The key features of this "version 1" will be:
+
+- Allowing for all tools to be installed in a single command, `pip install brainglobe`.
+- A reorganisation of the functionality offered by some tools (notably `cellfinder` and `brainreg`).
+- To provide a stable, citable release of all existing BrainGlobe tools that can be found in a single place.
+
+The individual tools (and the packages that provide them) will be remaining separate, so users can continue to manage and install individual tools if they so choose.
+
+## What is changing?
+
+One of our priorities with version 1 is that users should have to change as little as possible when they update.
+Whilst the majority of changes are happening "under the hood", the way users interact with them through napari or the package API will change minimally and should be limited to the renaming certain tools or functions.
+However we will be releasing changelogs for the individual tools as they are updated, as well as a final changelog with a complete listing of what tools have moved/changed and where to find them or their replacement.
+
+Changes will be happening in a modular fashion, before the all-in-one `brainglobe` package is then released at the end.
+This means that tools like `brainreg`, then `cellfinder`, etc will receive separate version updates as they are ready.
+There should be no ill affects from updating the tools as they are released, however once the all-in-ine `brainglobe` package is ready we recommend you make a clean install anyway, just so that there's no funny business.
+
+## Under the hood?
+
+Under-the-hood, we are taking this opportunity to create an easily-citable and stable version of each of our tools, as well as perform some much needed housekeeping on how we organise the tools themselves.
+This includes merging napari plugins with their corresponding "backend" tool; so to use `brainreg` with napari, users won't need to install `brainreg` and then also install `brainreg-napari`, for example.
+It also includes a renaming of a few tools that have since grown out of their original purpose; the workflow methods currently in `cellfinder` will move into a dedicated tool for running analysis, and `cellfinder-core` and `cellfinder-napari` will now be incorporated into the `cellfinder` package itself rather than being standalone.
+Finally, this will also simplify the number of inter-dependencies that we need to manage between our tools, and prevents issues surrounding modular installations from affecting users.
+We are not *removing* the option of manual installation of individual tools from the users that want to do this, however at the same time we are taking away this concern from users who want to jump right into using BrainGlobe's features without worrying if they have the right tool installed or setup correctly.
+
+## How can I stay updated?
+
+The blog will be updated as the modular updates progress, as well as with the final announcement when everything is ready.
+You can also [join us on Zulip](https://brainglobe.zulipchat.com/) and head over to the development stream to see live updates as development progresses.
From 7f806a6045ace255cc6649f7e969cb1436e88335 Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Tue, 31 Oct 2023 09:57:25 +0000
Subject: [PATCH 04/10] Add annoucement banner
---
docs/source/conf.py | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9f5f06b9..4b111ec2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -107,6 +107,7 @@
## Cutomize the theme
html_theme_options = {
+ "announcement": "BrainGlobe version 1 is under development! Keep track of the latest developments on the blog page",
"icon_links": [
{
# Label for this link
From 27f67e71c43a2ffad8c7cae2e03a35c0f79cd96b Mon Sep 17 00:00:00 2001
From: Will Graham <32364977+willGraham01@users.noreply.github.com>
Date: Tue, 31 Oct 2023 10:41:22 +0000
Subject: [PATCH 05/10] Apply suggestions from code review
Co-authored-by: Adam Tyson
---
docs/source/blog/version1/version_1_annoucement.md | 6 +++---
docs/source/conf.py | 2 +-
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/source/blog/version1/version_1_annoucement.md b/docs/source/blog/version1/version_1_annoucement.md
index c259c2e4..f6a47e5b 100644
--- a/docs/source/blog/version1/version_1_annoucement.md
+++ b/docs/source/blog/version1/version_1_annoucement.md
@@ -7,10 +7,10 @@ category: BrainGlobe-v1
language: English
---
-# BrainGlobe version 1 is coming
+# BrainGlobe is being restructured, version 1 is on it's way!
BrainGlobe provides and maintains a number of open-source tools, each of which are provided as Python-based software packages.
-A number of these tools also come with a user-interface provided by a [napari plugin](https://napari.org/) that can be installed on top of the basic tool package.
+A number of these tools also come with a graphical user-interface provided by a [napari plugin](https://napari.org/) that can be installed on top of the Python package.
Whilst there is an advantage to the modularity provided by maintaining separate tools, the same modularity can present challenges and unnecessary difficulties when running an analysis that relies on multiple BrainGlobe tools.
Particular pinch points include:
@@ -35,7 +35,7 @@ However we will be releasing changelogs for the individual tools as they are upd
Changes will be happening in a modular fashion, before the all-in-one `brainglobe` package is then released at the end.
This means that tools like `brainreg`, then `cellfinder`, etc will receive separate version updates as they are ready.
-There should be no ill affects from updating the tools as they are released, however once the all-in-ine `brainglobe` package is ready we recommend you make a clean install anyway, just so that there's no funny business.
+There should be no ill affects from updating the tools as they are released, however once the all-in-one `brainglobe` package is ready we recommend you make a clean install anyway, just so that there's no funny business.
## Under the hood?
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4b111ec2..e294d3b6 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -107,7 +107,7 @@
## Cutomize the theme
html_theme_options = {
- "announcement": "BrainGlobe version 1 is under development! Keep track of the latest developments on the blog page",
+ "announcement": "BrainGlobe is undergoing restructuring. Keep track of the latest developments on the blog",
"icon_links": [
{
# Label for this link
From fbf83551d8be8d58e5afb2d2769c9e42261137ee Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Tue, 31 Oct 2023 10:49:12 +0000
Subject: [PATCH 06/10] Include authors in blog listings
---
docs/source/blog/index.md | 2 +-
.../{version_1_annoucement.md => version_1_announcement.md} | 0
2 files changed, 1 insertion(+), 1 deletion(-)
rename docs/source/blog/version1/{version_1_annoucement.md => version_1_announcement.md} (100%)
diff --git a/docs/source/blog/index.md b/docs/source/blog/index.md
index 29957126..d2bcbe3a 100644
--- a/docs/source/blog/index.md
+++ b/docs/source/blog/index.md
@@ -9,7 +9,7 @@ Check here for changelogs and package updates as they are released.
:list-style: circle
:category: BrainGlobe-v1
:date: "%Y-%m-%d"
-:format: "{date} - {title}"
+:format: "({date}) {title}, by {author}"
:excerpts:
:sort:
```
diff --git a/docs/source/blog/version1/version_1_annoucement.md b/docs/source/blog/version1/version_1_announcement.md
similarity index 100%
rename from docs/source/blog/version1/version_1_annoucement.md
rename to docs/source/blog/version1/version_1_announcement.md
From 9326f079f2cc31ca4ed34789e811924c441e8ba7 Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Tue, 31 Oct 2023 11:10:43 +0000
Subject: [PATCH 07/10] Expand on cellfinder update
---
.../blog/version1/version_1_announcement.md | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
diff --git a/docs/source/blog/version1/version_1_announcement.md b/docs/source/blog/version1/version_1_announcement.md
index f6a47e5b..0ef84135 100644
--- a/docs/source/blog/version1/version_1_announcement.md
+++ b/docs/source/blog/version1/version_1_announcement.md
@@ -18,12 +18,12 @@ Particular pinch points include:
- Propagation of legacy naming conventions, as tools have evolved and their purpose has been redefined.
- Complex dependency trees, further complicated by optional dependencies.
-To address these issues, we are pleased to announce that development on "BrainGlobe version 1" is underway.
+To address these issues, we are pleased to announce that development of "BrainGlobe version 1" is underway.
The key features of this "version 1" will be:
- Allowing for all tools to be installed in a single command, `pip install brainglobe`.
- A reorganisation of the functionality offered by some tools (notably `cellfinder` and `brainreg`).
-- To provide a stable, citable release of all existing BrainGlobe tools that can be found in a single place.
+- To provide a stable release of all existing BrainGlobe tools that can be found in a single place.
The individual tools (and the packages that provide them) will be remaining separate, so users can continue to manage and install individual tools if they so choose.
@@ -39,9 +39,9 @@ There should be no ill affects from updating the tools as they are released, how
## Under the hood?
-Under-the-hood, we are taking this opportunity to create an easily-citable and stable version of each of our tools, as well as perform some much needed housekeeping on how we organise the tools themselves.
+Under-the-hood, we are taking this opportunity to create a stable version of each of our tools, as well as perform some much needed housekeeping on how we organise the tools themselves.
This includes merging napari plugins with their corresponding "backend" tool; so to use `brainreg` with napari, users won't need to install `brainreg` and then also install `brainreg-napari`, for example.
-It also includes a renaming of a few tools that have since grown out of their original purpose; the workflow methods currently in `cellfinder` will move into a dedicated tool for running analysis, and `cellfinder-core` and `cellfinder-napari` will now be incorporated into the `cellfinder` package itself rather than being standalone.
+It also includes a renaming of a few tools that have since grown out of their original purpose; [the `cellfinder` tool in particular will cease to exist](#appendix-a-note-on-cellfinder), but the functionality will be preserved somewhere else in BrainGlobe.
Finally, this will also simplify the number of inter-dependencies that we need to manage between our tools, and prevents issues surrounding modular installations from affecting users.
We are not *removing* the option of manual installation of individual tools from the users that want to do this, however at the same time we are taking away this concern from users who want to jump right into using BrainGlobe's features without worrying if they have the right tool installed or setup correctly.
@@ -49,3 +49,13 @@ We are not *removing* the option of manual installation of individual tools from
The blog will be updated as the modular updates progress, as well as with the final announcement when everything is ready.
You can also [join us on Zulip](https://brainglobe.zulipchat.com/) and head over to the development stream to see live updates as development progresses.
+
+## Appendix: a note on `cellfinder`
+
+The tool currently known as `cellfinder`; which provides a workflow (available on the command line or through a graphical interface) for performing whole-brain cell detection, registration, and analysis, will be undergoing a slightly more significant restructuring than the other tools.
+The functionality (and workflow) that this tool provides will be preserved, however will no longer carry the name `cellfinder`.
+This change makes the tool to be more descriptive of *what the user will want the workflow to do*, rather than being a reference to what the underlying Python package contains code for, which is the current status.
+Making this change also allows the the packages `cellfinder-core` and `cellfinder-napari` (which contain the aforementioned Python code that `cellfinder` depended on and takes its name from) to take up the name `cellfinder`, which is helpful organisationally for us as developers.
+Beyond the change in name, users will not have to worry about the internal changes that are occurring to the `cellfinder` package, as one of the features of "BrainGlobe version 1" will be to provide a one-line install that takes care of this for them.
+
+As [mentioned previously](#how-can-i-stay-updated), a complete list of changes and a reference for finding tools that have moved will be published as tools are updated.
From ad9a2316b93b2dcffe65554c95aafd81fbdbf9e3 Mon Sep 17 00:00:00 2001
From: willGraham01 <1willgraham@gmail.com>
Date: Tue, 31 Oct 2023 11:11:50 +0000
Subject: [PATCH 08/10] Remove category filter on blog post listing
---
docs/source/blog/index.md | 7 +------
1 file changed, 1 insertion(+), 6 deletions(-)
diff --git a/docs/source/blog/index.md b/docs/source/blog/index.md
index d2bcbe3a..5c9e8c15 100644
--- a/docs/source/blog/index.md
+++ b/docs/source/blog/index.md
@@ -1,13 +1,8 @@
# Blog
-## BrainGlobe version 1
-
-All announcements containing information on the progress of the release of BrainGlobe v1.
-Check here for changelogs and package updates as they are released.
-
```{postlist}
:list-style: circle
-:category: BrainGlobe-v1
+:category:
:date: "%Y-%m-%d"
:format: "({date}) {title}, by {author}"
:excerpts:
From 262769f540d25e186c8eeb6f1338731535848e15 Mon Sep 17 00:00:00 2001
From: Will Graham <32364977+willGraham01@users.noreply.github.com>
Date: Tue, 31 Oct 2023 11:55:39 +0000
Subject: [PATCH 09/10] Apply suggestions from code review
Co-authored-by: Adam Tyson
---
docs/source/blog/version1/version_1_announcement.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/source/blog/version1/version_1_announcement.md b/docs/source/blog/version1/version_1_announcement.md
index 0ef84135..d12478ac 100644
--- a/docs/source/blog/version1/version_1_announcement.md
+++ b/docs/source/blog/version1/version_1_announcement.md
@@ -52,8 +52,8 @@ You can also [join us on Zulip](https://brainglobe.zulipchat.com/) and head over
## Appendix: a note on `cellfinder`
-The tool currently known as `cellfinder`; which provides a workflow (available on the command line or through a graphical interface) for performing whole-brain cell detection, registration, and analysis, will be undergoing a slightly more significant restructuring than the other tools.
-The functionality (and workflow) that this tool provides will be preserved, however will no longer carry the name `cellfinder`.
+The tool currently known as `cellfinder`; which provides a command line workflow for performing whole-brain cell detection, registration, and analysis, will be undergoing a slightly more significant restructuring than the other tools.
+The functionality (and workflow) that this tool provides will be preserved and moved to another package.
This change makes the tool to be more descriptive of *what the user will want the workflow to do*, rather than being a reference to what the underlying Python package contains code for, which is the current status.
Making this change also allows the the packages `cellfinder-core` and `cellfinder-napari` (which contain the aforementioned Python code that `cellfinder` depended on and takes its name from) to take up the name `cellfinder`, which is helpful organisationally for us as developers.
Beyond the change in name, users will not have to worry about the internal changes that are occurring to the `cellfinder` package, as one of the features of "BrainGlobe version 1" will be to provide a one-line install that takes care of this for them.
From 5455407a86168ab413106615c1996a2d434e99ea Mon Sep 17 00:00:00 2001
From: Will Graham <32364977+willGraham01@users.noreply.github.com>
Date: Tue, 31 Oct 2023 13:48:05 +0000
Subject: [PATCH 10/10] Update
docs/source/blog/version1/version_1_announcement.md
---
docs/source/blog/version1/version_1_announcement.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/source/blog/version1/version_1_announcement.md b/docs/source/blog/version1/version_1_announcement.md
index d12478ac..c2b2f920 100644
--- a/docs/source/blog/version1/version_1_announcement.md
+++ b/docs/source/blog/version1/version_1_announcement.md
@@ -54,7 +54,7 @@ You can also [join us on Zulip](https://brainglobe.zulipchat.com/) and head over
The tool currently known as `cellfinder`; which provides a command line workflow for performing whole-brain cell detection, registration, and analysis, will be undergoing a slightly more significant restructuring than the other tools.
The functionality (and workflow) that this tool provides will be preserved and moved to another package.
-This change makes the tool to be more descriptive of *what the user will want the workflow to do*, rather than being a reference to what the underlying Python package contains code for, which is the current status.
+This change allows us to better distinguish between the workflow that the tool provides, and the "backend" Python code that the workflow depends on.
Making this change also allows the the packages `cellfinder-core` and `cellfinder-napari` (which contain the aforementioned Python code that `cellfinder` depended on and takes its name from) to take up the name `cellfinder`, which is helpful organisationally for us as developers.
Beyond the change in name, users will not have to worry about the internal changes that are occurring to the `cellfinder` package, as one of the features of "BrainGlobe version 1" will be to provide a one-line install that takes care of this for them.