Remove Darkfish and JsonIndex generators

[st0012]

With Aliki, we don't need these 2 generators anymore. Removing them will allow us to do more cleanups/improvements in the future.

After this is merged, I'll see how we can re-architect Aliki's generator logic.

[matzbot]

🚀 Preview deployment available at: https://c67d39c7.rdoc-6cd.pages.dev (commit: fd18e20)

[hsbt]

I don't think there's any problem with removing it, but how about extracting it as rdoc-darkfish-theme or something?

Someone might want to use it in future versions of rdoc.

[st0012]

@hsbt But extracting it means that we'll still need to test it and do some kind of maintenance for it (update Ruby, update dependencies...etc).
I'm probably biased as Aliki creator, but to me Darkfish doesn't provide enough value to warrant these effort. If some users want to use Darkfish due to extensibility etc, we should put the effort into making Aliki work for those cases instead.

[vinistock]

Considering that users can have Darkfish customizations that don't apply to Aliki (breaking change), do we need to add a deprecation notice prompting users to migrate first? Or do we already have that?

I'm all for removing and simplifying the codebase, just trying to be careful about breaking changes that might be impactful for projects.

[st0012]

@vinistock We don't have runtime deprecation and it's a bit late to add it now because the Prism-based parser change has been merged and the next release have to be a major release.

We did add this in the readme when changing the default them to Aliki:

Darkfish (deprecated) - The classic theme, will be removed in v8.0

And let me provide a bit more context about customizing themes in RDoc. There are 2 ways to do it:

1. You create a new generator class, which will then handle things from data collection to asset locations to template rendering
2. You create only assets and templates, and use --tempalte flag to run the current default generator with them

So this PR will definitely break anything that does 1 using Darkfish class as a superclass. BUT, there's no known theme that's based on the Darkfish generator this way, and received any update in the last 10 years, as shown by GH search result. I did this search 2 years ago when trying to renovate Darkfish. And I didn't find anything back then either.

As for themes using approach 2, because Aliki generator's implementation is still largely the same as Darkfish's, they should be unaffected by this change. I tested it with rorvswild-theme-rdoc, the only theme I know using this approach. And it's still working.

I also want to point out approach 2 is EXTREMELY fragile. Because the way templates are rendered using the generator object's binding, those templates have access to ALL methods, including private ones, and ALL ivars. So just renaming an ivar in Aliki generator could break themes doing it. As a result, I actually want to ban approach 2 going forward. But I can wait another major release for this.

[vinistock]

I agree that it's extremely fragile and it's a pattern that I would love to change. My main concern is for big projects with customizations, for example Rails' sdoc, which patches many internals of RDoc and includes a bunch of templates of their own. It might be worth giving them a heads up.

[st0012]

SDoc uses its own generator, which doesn't inherit/reference Darkfish. So I think they're good here.

@p8 can you help me confirm if it's true that SDoc would not be affected by this change?

[st0012]

FWIW, I ran SDoc's tests against this branch and it doesn't create additional failures (some tests are failing because RDoc's anchor/Prism parser changes).