consider using sphinx-immaterial #2894
Description
@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.
@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.
Activity
dikwickley commentedon Mar 7, 2025
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 commentedon Mar 7, 2025
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 commentedon Mar 7, 2025
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 commentedon Mar 7, 2025
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 commentedon Mar 8, 2025
i think this looks really good
dikwickley commentedon Mar 9, 2025
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 commentedon Mar 10, 2025
Switching from using the numpydoc extension to using sphinx.ext.napoleon should fix at least some of the issues.
jbms commentedon Mar 12, 2025
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 commentedon Mar 13, 2025
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 commentedon Mar 21, 2025
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 commentedon Mar 21, 2025
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 commentedon May 23, 2025
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.