consider using sphinx-immaterial

[d-v-b]

@jbms maintains an excellent theme for sphinx that (IMO) looks much cleaner than our current theme. I would be interested in seeing what our docs page could look like with that theme.

[dikwickley]

Here is a sample: https://zarr--2899.org.readthedocs.build/en/2899/quickstart.html

it's missing the announcement banner, it can be added though: https://jbms.github.io/sphinx-immaterial/customization.html#new-blocks

[jbms]

Note that to take full advantage, you may want to use the python-apigen extension (replaces autosummary):

https://jbms.github.io/sphinx-immaterial/apidoc/python/apigen.html

[jbms]

There is also support for JSON schemas as a Sphinx domain, which may not be too useful for zarr-python but could be very useful for the zarr spec:

https://google.github.io/tensorstore/driver/zarr3/index.html#json-driver/zarr3/Metadata

[jbms]

I see that the API documentation is displaying with weird spacing:

https://zarr--2899.org.readthedocs.build/en/2899/api/zarr/index.html

Not sure if that is a bug in the theme, or caused by some custom css that you have.

[d-v-b]

i think this looks really good

[dikwickley]

Code blocks in API ref looks really weird. https://zarr--2899.org.readthedocs.build/en/2899/api/zarr/index.html
not sure if this is due to some existing configuration

[jbms]

Switching from using the numpydoc extension to using sphinx.ext.napoleon should fix at least some of the issues.

[jbms]

I investigated this a bit more and identified a few bugs and limitations in the sphinx-immaterial theme. Those are now fixed, and I created a PR against the branch that @dikwickley created that makes this theme work much better:

dikwickley#1

[dikwickley]

thank you @jbms for the changes! but the build failed due to many warnings (that are treated as errors) :(

https://readthedocs.org/projects/zarr/builds/27490786/

[kylebarron]

Well... I understand if other developers are reticent, but you could just switch to mkdocs-material. It doesn't look like there's that much prose documentation that you'd need to convert, and I expect the docstrings would continue to work without changes.

I'm heavily biased because I love my mkdocs-based sites, and nowadays mkdocs has really excellent API documentation via mkdocstrings, but I figure that most projects that have been around for a while, like zarr, use sphinx because that was the only option when the project was created.

But this really revolves around whether the developers here actually prefer RST vs Markdown.

[d-v-b]

personally I would love to use mkdocs-material. And I would be surprised if there's anyone here who strongly prefers rst over markdown.

[maxrjones]

I'd like to start volunteering more time towards Zarr-Python and identified this as a good first issue to work on. I will open a PR with a mkdocs-based documentation structure for feedback within the next week or two.