Update Dask Docs Theme

[mrocklin]

This theme hasn't been touched in a while. Maybe it's time for a refresh.

I notice folks using the material theme of MkDocs often these days, and I'll admit to being a little jealous. That would probably be a bigger lift, but maybe worth it? (looking good in docs is important).

cc @scharlottej13 @jacobtomlinson @jrbourbeau @quasiben

[jacobtomlinson]

I feel like the material theme is overused. I still like the Sphinx Book theme, but we could do with updating to a more recent version #68.

[mrocklin]

Are there some sites that use a recent sphinx book theme that you really like? I'd like to peruse around a little.

[jacobtomlinson]

This gallery is probably a good place to look. https://executablebooks.org/en/latest/gallery/

I also really like the MyST theme shown here https://youtu.be/sTvx3u1hXME?si=0-uh9SIN2PMd2hjR&t=1051

[mrocklin]

I'm curious, what are some things you like about the sphinx book theme over material-mkdocs?

To be clear, I'm not pushing hard. Genuinely curious in the design conversation.

[jacobtomlinson]

Material looks great, but it just seems to look the same everywhere.

If you look at the Textual docs compared with the FastAPI docs they just look the same. I feel like switching to the theme that everyone is using because everyone is using it means we will just blend into the trees.

Also the lift from Sphinx to mkdocs in non-trivial (I've gone in the other direction in other projects and it was hard work).

I would love for the Dask docs to look more like the design of dask.org, rather than making it look more like every other Python project from the last couple of years.

[mrocklin]

Sure, so mostly what I'm hearing from you is a desire to be distinct. It's not that you think that the sphinx-book styling is better, it's just less used, and so it sets us apart a bit. Correct?

Presumably if someone used material+mkdocs but styled it nicely you'd be in favor (technical switching costs aside)

[jacobtomlinson]

That's part of it. If material can be sufficiently customised then I'm fine with the design, it just feels a bit safe and boring.

The other part is a concern about tooling. If you have a strong desire to use material that would create a lot of consequences in terms of RST/MyST -> vanilla Markdown migration along with RTD changes and other CI things. We have a lot of institutional knowledge around Sphinx and the common plugins we use. Switching to mkdocs just to use a different theme feels like a bad use of our limited community resources.

Surely a popular Sphinx theme like book or PyData could also be used as a base?

[mrocklin]

Let's see, maybe it's on me to list some of the things I like about sites I'm seeing using Material+MkDocs. Maybe that'll help us understand what we could do within Sphinx and what we couldn't (I agree with you that there's value to sticking with sphinx). I'm using the delta-rs and sphinx-book-theme docs for each.

Let's start with these two images

Things I like about Material+MkDocs over Sphinx-book-theme here:

• Font weights in material seem thinner, which gives a more modern appearance I think
• Less clutter on the sidebar. All of the non-docs stuff is up in the topbar while the content is alone below
• Color in sphinx-book-theme seem kinda all over the place (the link hover is orange for some reason (Jupyter?)) while colors in material seem more sedate / open to the project to define

Search bar

The searchbar in sphinx-book-theme seems unattractive to me

Material+MkDocs seems quite nice in comparison

[mrocklin]

A lot of that we could do within Sphinx-book-theme. My sense is that it would take some design work.

Again, I'm not pushing for anything to happen right now (there isn't some imminent "change-all-the-docs" plan in Coiled right now or anything) but if that were to come (which I'd be excited by) I don't think I'd hold too closely to Sphinx. You're right that we have more collective experience wth sphinx, but also no one has touched this repo in years, so it's not like we're actually leveraging that experience. If the Dask sphinx theme was under active development from a thriving developer community (or heck, even just one person) then I'd be a lot more hesitant to change things drastically. As it is though it seems to me like no one is really innovating here, and so if innovation does happen we should be pretty open about the direction that it takes.

[mrocklin]

Going in the direction of dask-sphinx-theme @jacobtomlinson do you know anyone who you think is really good at styling sphinx pages and making them look more modern? I'd be happy to throw some money at this problem if there's an easy solution.

[jacobtomlinson]

I agree with all of that. Although I would point out that people use Sphinx and this theme all the time in Dask projects, even if the theme itself hasn't needed to change much recently, that's the knowledge I was referring to.

All of the design things you like about material I agree with, but they are superficial things that can be easily tweaked in CSS. I was expecting you to give examples of more fundamental feature differences if we are talking about switching theme/tooling.

If someone wants to step in and drive things here that would be great. If someone wants to spend the time to migrate all of the repos to another setup then power to them. But given that the current theme is "fine" it feels like a pretty low priority activity. I would much prefer someone to spend time on making CI more stable than iterating on the docs theme.

[mrocklin]

Although I would point out that people use Sphinx and this theme all the time in Dask projects, even if the theme itself hasn't needed to change much recently, that's the knowledge I was referring to

Sure, I guess that even there I don't see a ton of activity happening with the dask-sphinx-theme. The last time I tried using it (for the etl project) I was actually pretty sad about how dated it was (sphinx 4!) and wished that we had access to something newer.

All of the design things you like about material I agree with

👍

but they are superficial things that can be easily tweaked in CSS.

Ah, this might be easier for you than for me. For me it's easier to just onboard a new system than to figure out good design and implement that design in CSS.

I was expecting you to give examples of more fundamental feature differences if we are talking about switching theme/tooling.

Nope. To be clear, I perceive the look and feel of the docs to be the most important thing besides the content itself. I don't think that there's any feature of a docs platform that I would weight more highly than how it looks. (assuming that it's a simple static site generator at least).

If someone wants to step in and drive things here that would be great

Any interest in collaborating here? I'll be that you and I working together could do some good work in small time.

But given that the current theme is "fine" it feels like a pretty low priority activity. I would much prefer someone to spend time on making CI more stable than iterating on the docs theme

With my user-focus hat on I think I disagree with you here (thousands of users see the docs, and impressions are important). But prioritization is mostly up to people doing/supporting the work, so maybe not a highly relevant conversation here. (unless having that conversation convinces you to jump in here and collaborate a bit!)

[jacobtomlinson]

I perceive the look and feel of the docs to be the most important thing besides the content itself

I agree, but I also rate the developer experience of writing docs a close second. Switching many projects from RST to Markdown (and not MyST but the mkdocs flavour) would be a big burden. I would rather invest effort in moving to a newer Sphinx instead.

Any interest in collaborating here?

That sounds fun! I'm not going to be available until late March due to GTC. Does that timeline work?

[mrocklin]

Yeah! That could work!

On Tue, Mar 5, 2024, 11:09 AM Jacob Tomlinson @.***> wrote:

I perceive the look and feel of the docs to be the most important thing besides the content itself

I agree, but I also rate the developer experience of writing docs a close second. Switching many projects from RST to Markdown (and not MyST but the mkdocs flavour) would be a big burden. I would rather invest effort in moving to a newer Sphinx instead.

Any interest in collaborating here?

That sounds fun! I'm not going to be available until late March due to GTC. Does that timeline work?

— Reply to this email directly, view it on GitHub https://github.com/dask/dask-sphinx-theme/issues/86#issuecomment-1979246707, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACKZTAH5IDRCGS4Y2SZYP3YWX33ZAVCNFSM6AAAAABEGD476WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNZZGI2DMNZQG4 . You are receiving this because you authored the thread.Message ID: @.***>