zarr-developers
Use mkdocs-material instead of sphinx
@kylebarron has been subtly 🙈 advocating for mkdocs over sphinx for Python projects because they look nice and don't involve any RST. I haven't used mkdocs, but am curious so I thought I'd move the comment to a specific issue for discussion.
Originally posted by @kylebarron in https://github.com/zarr-developers/VirtualiZarr/pull/490#discussion_r2010683170
I don't like writing RST but other than that don't have an opinion. If there is a solution that lets us have executable markdown docs that sounds great.
I think the closest thing to what you probably mean is the https://github.com/danielfrg/mkdocs-jupyter. I've used it in Lonboard e.g. here, but in Lonboard I don't include the notebook outputs because the Jupyter notebook - ipywidgets - mkdocs - html integration doesn't work (at least for lonboard specifically)
We don't really need html integration to work for virtualizarr (the printable representation is fine), but we definitely do want the cells to actually be executed by the docs build. See https://github.com/zarr-developers/VirtualiZarr/pull/486
cc @ianhi
Oh ok, so it's already in notebook form anyways. That should be easy (famous last words) to switch and prototype in mkdocs
My experience is that the mkdocs ecosystem is less well developed for notebooks than the equivalent using myst/jupyterbook
If the primary motivation for the swap is the looks we can also use https://jbms.github.io/sphinx-immaterial/
https://github.com/danielfrg/mkdocs-jupyter allows you to execute notebooks when building docs.
To be clear I'm not even a committer here at this point, so don't change just for me. But I've had tons of pain in the past with both sphinx and RST. So from my perspective it's not so much as the looks as the ease-of-use for developing the site and writing documentation that mkdocs, mkdocs-material, and mkdocstrings make way easier and simpler today.
To be clear I'm not even a committer here at this point, so don't change just for me. But I've had tons of pain in the past with both sphinx and RST.
I very much want to be able to move docs in all my projects to markdown, as long as the key features like executable code snippets still work. But I also don't want to have to learn about it, so I appreciate you coming in here with an opinionated recommendation 😀
But I'm not clear from this discussion which set of tools we should use to stay on the right train going forward...
Well my opinionated recommendation, which you can see in lonboard and obstore (and every other Python docs site I've made in the last 5 years):
- mkdocs for the core markdown parsing and static site generation
- mkdocs-material for the theme
- mkdocstrings for automatic API docs and sphinx-compatible inter-linking
- mike for deploying different docs for different versions
- mkdocs-jupyter for executable examples
- mkdocs-redirects to move pages around without breaking links
You could basically copy the lonboard or obstore mkdocs.yml and start from there