Restructure "Getting Started" page to a "User Guide"

[niksirbi]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Restructuring docs

Why is this PR needed?

On the website we currently use the "Getting Started" section as a catch-all term for "any content that's not an example and not community-related". Some things in there would really fit well under "Getting Started" - for example the installation - but others include deep dives that are more akin to "conceptual guide" (e.g. explaining the data structure).

I think "Getting started" does not represent this collection well. Moreover, I plan on writing an actual "Quickstart" page that will walk through a basic movement workflow, see #284, and the two terms may be confusing.

What does this PR do?

1. Renames the current "Getting Started" section to a "User guide", which can serve us in the near future as a generic container for a bunch of things, including: the current contents, a napari guide, a conceptual explanation of coordinate systems, etc. At a later time-point we may wish to diataxis-ize thing by separating how-to guides from conceptual guides, but we are not there yet I think.

This is how our homepage will look with this change:

I configured some redirects such that old links will still resolve correctly despite the renaming. I tested those locally, and by inspecting the contents of build/html and it all seems to work out nicely.

With #284, a fourth card will be added to the above three, probably named "Quickstart" or "Walkthrough", and it will probably be the first card shown.

2. I also added cards to the new "User Guide" landing page. I find these more aesthetically pleasing than just dumping the TOC, which is what we currently have there.

This is how the "User guide" page will look like with my proposed change:

The idea is that cards will proliferate as we add more guides. Feel free to push back on this aesthetic choice, I don't feel very strongly about it.

3. I moved the "Sample data" page as a sub-section of the "Input/Output" page. That's because it kinda conceptually belongs there and it didn't feel important enough to deserve its own card.

References

This PR sets the stage for #283 and #284.

How has this PR been tested?

Local documentation build.

Is this a breaking change?

No, because of the redirects, old links should work.

Checklist:

• [n/a] The code has been tested locally
• [n/a] Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.78%. Comparing base (85904d9) to head (072f648).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #353   +/-   ##
=======================================
  Coverage   99.78%   99.78%           
=======================================
  Files          14       14           
  Lines         912      912           
=======================================
  Hits          910      910           
  Misses          2        2           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[niksirbi]

Following the feedback I received during out 2024-11-29 meeting, I've made the following modifications to this PR:

1. Removed the redirects because we thought such a redirect list would be a burden to maintain, see commit c15cd9e.
2. Instead configured a custom 404 page, using the sphinx-notfound-page extensions, following what BrainGlobe does for their website (closes Create a custom 404 page #354). I haven't found a way to really test this locally, but at least I can confirm that 404.html is being generated in the build folder. See commit fdadf5d.
3. Spellt section headers with sentence capitalisation. In practice this means using "User guide" instead of "User Guide", and "API reference" instead of "API Reference". I've kept "Input/Output" as is. The other headers were all following sentence capitalisation anyway, see commit 96ccbc6.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[lochhh]

Thanks @niksirbi, all LGTM 🚀 ! Except we may have to recreate the PR as it looks like the PR is stuck in "Processing updates" after I accidentally pushed a commit (which has now been removed) to the ns-user-guide branch while testing your changes. I tried making an empty commit to get the PR unstuck, and this worked, but then when I once again try to remove this commit from the branch, we're back to being stuck 😅

[niksirbi]

I tried making an empty commit to get the PR unstuck, and this worked, but then when I once again try to remove this commit from the branch, we're back to being stuck 😅

That's super weird, I've never seen this bug before. Anyhow I've opened #356, so I will close this one as superseded by that one.