Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: main
Choose a base branch
from

Conversation

maxrjones
Copy link
Member

@maxrjones maxrjones commented Jun 6, 2025

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

@github-actions github-actions bot added the needs release notes Automatically applied to PRs which haven't added release notes label Jun 6, 2025
@d-v-b
Copy link
Contributor

d-v-b commented Jun 7, 2025

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs release notes Automatically applied to PRs which haven't added release notes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

consider using sphinx-immaterial
2 participants