[docs] remove primary sidebar from tutorial

[sneakers-the-rat]

pydata-sphinx-theme has a dual-sidebar system that makes some pretty specific assumptions about the structure of docs to work well, but has some odd behaviors otherwise. This PR makes the tutorial page look a little tidier.

Current Behavior

Currently on the tutorial page, the primary sidebar is totally empty. on wide screens, this is sort of a curiosity, but it becomes a nuisance on narrower screens. More than anything is just looks weird and unfinished (not your fault, byproduct of the theme)

Wider than medium breakpoint:

Below medium breakpoint:

This PR

Thankfully pydata-sphinx-theme also gives us nice control over the sidebars! Simply removing the primary sidebar makes it look tidier and uses screen space better.

Wider than medium breakpoint:

Below medium breakpoint:

Alternatively...

Another option is to move the page toc to the primary sidebar, which makes it stay visible at narrower widths:

html_theme_options = {
    # ...
    "secondary_sidebar_items": {
        "tutorial": []
    }
}

html_sidebars = {
    "tutorial": ["page-toc"]
}

Below medium breakpoint:

Went with the first one, but can switch to the second easily if that's preferred. This is also true of the other pages in the docs, but didn't want to change too much at once before knowing if this is desirable or not.

TODO:

• Add unit tests and/or doctests in docstrings (not needed)
• Add docstrings and API docs for any new/modified user-facing classes and functions (none modified)
• New/modified features documented in docs/tutorial.rst (none modified)
• Changes documented in docs/release.rst (it's a change to the docs layout! not documentable)
• GitHub Actions have all passed (hopefully)
• Test coverage is 100% (Codecov passes) (also hopefully)

[d-v-b]

Thanks for looking at this. I agree that the empty sidebar looks weird / sad, but I think the fundamental problem is that we haven't partitioned the tutorial content at the right level of detail for the left sidebar; so my preferred fix would be to break the tutorial content into a few high-level sections like "Quickstart", "Arrays", "Groups", "Storage", "Scaling", and then those links would appear in that left sidebar. Curious to hear what others think.

[joshmoore]

At the moment, I don't have a strong feeling either way, but I imagine there will be much work coming on the tutorial over the next weeks. There will need to be sections on v2 vs. v3, async vs. sync, etc.

[sneakers-the-rat]

Sure, up to y'all - this is true on a few of the docs pages, so if restructuring the docs is the route y'all would rather take, go ahead and close this, I just wasnt going to propose an unsolicited docs restructure :p

[d-v-b]

The underlying problem is real, so I think we can keep this PR open until we address that problem one way or another. @sneakers-the-rat maybe you could state the problem in a new issue, and link to this PR as a potential solution? Otherwise I can write it up.

edit: I fat-fingered the "close issue" button. sorry for the noise

[dstansby]

I'd be pro this going into the main branch as a pragmatic fix for the v2 docs. Agree that there's not much point on the v3 branch as a re-write is happening soon.

@sneakers-the-rat could you rebsase on to the main branch?

[sneakers-the-rat]

Im afk until Monday but will do

[sneakers-the-rat]

rebased and linted :)

edit: idk what this failure is but i don't think it's from me? this shouldn't affect a wheel https://github.com/sneakers-the-rat/zarr-python/actions/runs/10782636431/job/29903003548

[sanketverma1704]

Thanks for working on this, @sneakers-the-rat.
I agree with @dstansby; let's get this in main and address this separately in the v3.

[dstansby]

Thanks!

[sneakers-the-rat]

Thanks to yall for making & maintaining this great tool ♥