V1 updates for brainreg changes

[willGraham01]

Closes brainglobe/BrainGlobe#39

Logs the changes that are being made to the brainreg, brainreg-napari, and brainreg-segment packages to the website.

Also starts on the brainglobe version 1 changelog page.

These pages are currently not linked to from anywhere on the website, although they are none-the-less accessible.

[adamltyson]

Thanks @willGraham01. I think this should go in somwhere other than documentation. documentation has so far contained mostly reference guides to using the s/w. Maybe we should create a development section, and also move the dev guides. Any ideas @alessandrofelder?

[willGraham01]

Maybe we should create a development section

We do already have a developers folder (and presumably page) so maybe it should go there? Although we probably want a front-facing "version 1 is coming" page too

[alessandrofelder]

Yea maybe we need a "Releases" section for changelogs? And a "Blogs" session somewhere close to the front for announcements such as this, that links to the relevant changelog?

[alessandrofelder]

I think this is separate from the general developer docs - it's an announcement that we mostly need users and developers of other packages (also a kind of user I guess) to be aware of?

[adamltyson]

We do already have a developers folder (and presumably page) so maybe it should go there?

We have a developers folder, but it's (currently) linked within documentation, so we should probably make that accessible somewhere else.

Yea maybe we need a "Releases" section for changelogs?

Ideally

And a "Blogs" session somewhere close to the front for announcements such as this, that links to the relevant changelog?

Yup, pydata-sphinx has a blogging extension we can use (we use it for https://neuroinformatics.dev/)

I think this is separate from the general developer docs - it's an announcement that we mostly need users and developers of other packages (also a kind of user I guess) to be aware of?

I think the blog can announce to everyone, and then this can link to specific docs for developers and/or users

FYI rather than changing the home page, we can add an announcement that links to the blog.

[willGraham01]

So end-goal would be a structure like the following (within docs/source):

blogs/
  version_1_announcement.md                      # Main "this is happening" announcement
  brainreg_updated_to_version_1_annoucement.md   # Added as incremental packages are updated
  cellfinder_updated_to_version_1_annoucement.md # etc
  brainglobe_vesion_1_released.md                # :partying_face: 

index.md        # Gets an announcement directing to version_1_annoucement.md

releases/
  v1/
    full_changelog.md          # High level overview, TL;DR style
    brainreg.md                # Detailed listing of what has changed name, 
    cellfinder.md              # where functionality has been moved to, etc, on a
                               # package-by-package basis
documentation/
  # Individual pages to be updated to version 1 compatible information as appropriate.

On my to-do list today / Tuesday is the Blog announcement so I can start a separate PR for that, then rebase this on top.

[adamltyson]

So end-goal would be a structure like the following (within docs/source):

blogs/
  version_1_announcement.md                      # Main "this is happening" announcement
  brainreg_updated_to_version_1_annoucement.md   # Added as incremental packages are updated
  cellfinder_updated_to_version_1_annoucement.md # etc
  brainglobe_vesion_1_released.md                # :partying_face: 

index.md        # Gets an announcement directing to version_1_annoucement.md

releases/
  v1/
    full_changelog.md          # High level overview, TL;DR style
    brainreg.md                # Detailed listing of what has changed name, 
    cellfinder.md              # where functionality has been moved to, etc, on a
                               # package-by-package basis
documentation/
  # Individual pages to be updated to version 1 compatible information as appropriate.

On my to-do list today / Tuesday is the Blog announcement so I can start a separate PR for that, then rebase this on top.

100% thanks!

[adamltyson]

Sorry @willGraham01 I didn't fully understand the structure you outlined earlier. I don't think releases should be in the top bar or in a card. I think it's just not important enough for most users for it to be presented so prominently.

As suggested by @niksirbi, what about a "community" section to bring some different parts together? I'll update this PR and you can take a look.

As an aside, can the blog list posts in reverse chronological order instead?

[willGraham01]

what about a "community" section to bring some different parts together? I'll update this PR and you can take a look.

No problem, shout when you've pushed things up. (I've just removed the releases card on the main page).

As an aside, can the blog list posts in reverse chronological order instead?

I assume so, I also thought that was the default. Let me investigate

[adamltyson]

I've added a new community section (where I will also eventually add the roadmap). Some of the sections there aren't as prominent as I would like, but I think we have to prioritise and make sure a small amount of the most useful information is presented first.

[alessandrofelder]

Great, thanks @willGraham01 and @adamltyson . Looks good and ready for the big merge!