New theme?

[antoinem]

Hello,

We’ve started a new theme derived from Darkfish.
You can see how it looks here:
https://basesecrete.github.io/rdoc/

As you can see, there are already quite a few changes (navigation, typography, colors, dark mode…).
We wanted to check if there was some interest, before we spend more time on it.

What do you think?

Cheers,
Antoine and Alexis

[st0012]

Thank you for proposing this 🙌
I'm open to accept new optional themes and here's my thought on this topic:

• To encourage more usage on this tool and documentation writing in Ruby in general, more theme options are needed (2~3 in rdoc may be the best?)
• While whether rdoc maintainers will be able to maintain them long-term is surely a concern, I think it's a risk we need to take to grow the community. It can also be mitigated a bit through clear communication (e.g. we'll do our best but only the default theme is officially supported)

WDYT? @colby-swandale

A few notes to this PR:

• Please submit document changes (e.g. update heading) in a separate PR
• The addition of super_classes should be extracted too
• Since it's a new theme, I think it's better to remove some references to darkfish like "Darkfish" Rdoc CSS.
• I'm not familiar with js best practices, but my understanding is that darkfish.js unlikely to follow much of them. So I'd love to see new theme implementations not following its pattern unless necessary. I know it may be already on your roadmap, but I want to explicitly point it out.

[alexisbernard]

Thanks for the feedback. I have extracted super_classes into its own PR.

I'm not familiar with js best practices, but my understanding is that darkfish.js unlikely to follow much of them. So I'd love to see new theme implementations not following its pattern unless necessary. I know it may be already on your roadmap, but I want to explicitly point it out.

We don't have specific plan for the JS. I think the less JS it contains, the better it is. We only added few lines of JS compared to Darkfish. Otherwise it could share the JS with Darkfish, but it would be more fragile.

[colby-swandale]

This template ticks several boxes of things people would like to see in darkhorse, particularly Table of Contents navigation & Dark Mode, the new Rails documentation site shows this off well. Introducing a new HTML template would add quite a significant load to maintain, so I would more like to see us pluck these features into darkhorse.

[antoinem]

I've deleted the new theme folder and copied the changes in the darkfish theme folder.

[st0012]

Why are we changing darkfish templates too?

[antoinem]

Colby said:

so I would more like to see us pluck these features into darkhorse.

So I deleted the new theme folder and modified the Darkfish templates.
Here, the sidebar toggle is rendered in the new topbar partial.
I would have preferred to keep it separated and fine-tune it until it eventually becomes the new default theme, but I understand adding a new theme would require more maintenance.
How would you like us to proceed?

[st0012]

Sorry I missed that comment. I strongly prefer having it as a new theme and maintain it in parallel at least for a while.
But given that Colby and I have contrary opinions now, I'd advise you to hold off any future changes until we reached an agreement 🙏

[st0012]

Introducing a new HTML template would add quite a significant load to maintain, so I would more like to see us pluck these features into darkhorse.

@colby-swandale It's darkfish, not darkhorse 🙂
While I agree it'll be hard to maintain, I don't think it's a good idea to suddenly accept a theme overhaul when it'll be directly synced to docs.ruby-lang.org. I strongly prefer having this PR just add a new theme, potentially marking it as experimental, then decide what to do next depends on how rorvswild and darkfish are updated later.

[simi]

IMHO good idea to keep it separate as well for some time and switch defaults at some point with major bump or so.

[colby-swandale]

Apologies, my suggestion has gotten lost in translation I think. I wasn't suggesting that the entire Darkfish template be replaced, Instead I was suggesting plucking specific features from this Pull Requests into new PRs that can be added to darkfish like Table of Contents, Dark mode etc. Of course any new changes to Darkfish will need to consider the existing theme and make suitable adjustments.

[miguno]

+1

This is IMHO a significant improvement over the status quo. Thanks a lot for your work!

[alexisbernard]

We moved the theme into it's own gem (https://github.com/BaseSecrete/rorvswild-theme-rdoc), so anyone can use it without waiting for merging.

If you would like to have it directly into RDoc, we will be very happy to update the PR.