[RFC] Use mkdocs-material for Zarr-Python documentation

[maxrjones]

This PR switches the docs from sphinx to mkdocs-material (closes #2894)

Preview: https://zarr--3118.org.readthedocs.build/en/3118/

Motivation for using mkdocs-material

• Markdown-first: Uses standard Markdown instead of reStructuredText, which is more widely known and easier to write
• Simpler configuration: Single YAML config file vs. complex Python configuration
• Lower learning curve: Much easier for new contributors to get started writing documentation
• Active development: Very actively maintained with frequent updates
• Growing ecosystem: Large community and extensive plugin ecosystem
• Modern UI/UX: Clean, professional design that feels contemporary
• More navigable API docs: The customization of the API reference pages makes classes and functions easier to find (this was my main problem with the existing doc's usability).

Changes

Apart from the conversion to markdown and configuration updates, I made the following changes:

• Remove talks/scipy2019/submission since it wasn't included in the docs
• Consolidate quickstart with the home page
• Consolidate about with the home page
• Remove roadmap since it's purpose has been completed

Review request context

I'm not looking for a final review here, but rather a general consensus on whether it's worth spending the time that'd be needed for the last 20% of polish.

TODO

• Update any syntax in docstrings
• Update doctests
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Setup versioning
• Add redirects

[d-v-b]

I love the way this looks! Thanks so much for working on this.

[d-v-b]

@zarr-developers/python-core-devs it would be good to get some feedback on this. Switching our docs is a big decision, and it only makes sense to put effort in this if everyone is aligned. I personally think we should 100% move to mkdocs-material, but it would be good to hear if there are any big objections to that.

Aesthetically, and in terms of user-friendliness, I think this PR represents a huge improvement. If we just consider the landing page, this:

is vastly better than this:

[joshmoore]

Apologies, I thought I had 👍'd previously. Now doing that retroactively in a general sense of the move and specifically for the style & the use of markdown.

But I agree that we need a careful review of the pages (and personally, I liked the cards on the landing page)

[sanketverma1704]

Thanks a lot for working on this, @maxrjones!
Looks great!

I love the switch from .rst to .markdown—it makes it easy to update and lowers the barrier for contribution.

I liked the cards on the landing page

I'm with Josh on this one. Can we also add cards in mk-docs?

[d-v-b]

i am actually strongly anti-cards, because they take up a huge amount of space that could be devoted to actual content.

Here's how much space the "user guide" link consumes in the mkdocs version in this PR:

Compare with the space used in our current version for the same information:

...and why do we need text on this card that explains what a user guide is? Isn't it evident that a user guide is a guide for users?

Similarly, if we take the "quick start" card, IMO the first thing people see when they come to the docs should be the "quick start" content. We shouldn't ask people to click on a link after coming to our docs to see how to use zarr. In max's PR, he puts that content front-and-center on the main page:

by contrast, the old docs waste a huge amount of space with the card, which also has a very confusing "person escaping from an industrial accident" icon:

So yeah, in summary part of what makes this PR great to me is the removal of the cards. They are dead weight from a UX POV.

[maxrjones]

While I prefer the no-cards version, I also believe it's preferable to decide based on the ease of use for people who aren't extremely familiar with the Zarr-Python documentation, because those people may be completely blocked or dissuaded from using the library whereas others will likely find their way anyways. I could do some polling on preferences if others agree with this philosophy.

I also think that the transition to mkdocs shouldn't be blocked by whether the home page has cards. If people think this'll take a while to decide on, I could add this style card for now to minimize the stylistic decisions included in this PR.

[jhamman]

I just spent some time here and wanted to give a big 👍 to the switch to mkdocs-material. I wanted to do this leading up to 3.0 but choose not to in order to avoid scope creep in the documentation update.

As for cards, I don't think this should bend the decision here either way. We should optimize for usability. If users can quickly find their way to the main sections of the docs, then I'm for dropping the cards.

[jni]

fwiw, using only markdown in sphinx docs is easy to do these days, including automatically running executable jupytext notebooks, which we use in the napari docs. Example page:

https://github.com/napari/docs/blob/main/docs/howtos/layers/image.md?plain=1

Output:

https://napari.org/stable/howtos/layers/image.html

Never been a fan of the material look, but maybe I'm just weird. I'd prefer contributing upstream to the pydata sphinx theme (including customisation options) vs switching to a completely different ecosystem. Completely happy to be outvoted here, just wanted to add an alternative viewpoint in case there's more people like me out there. 😂

[jni]

(in short, out of all the motivations, I only find the yaml configuration compelling...)

[maxrjones]

Thank you so much to everyone who's expressed opinions so far!

I'd greatly appreciate if anyone still lurking could share your comments before July 3, 2025. The motivation for this deadline is that I'd like to make progress on this PR over the long weekend in the U.S. but only if the change to mkdocs seems likely to be accepted.

[normanrz]

I think this looks great 👍 Definitely like the markdown! Had good experiences with mkdocs previously as well.

[TomAugspurger]

+1 to all of @jni's comments (including the "Completely happy to be outvoted here" bit; ultimately, ensuring that contributors are empowered and motivated to write good documentation is the most important thing. I can adapt if others prefer different systems).