Improve method source toggling

[st0012]

1. Source toggling control is now always displayed
   • If we think the buttons take too much space or are distracting, I'd be happy to accept ideas/PRs for styling improvements. But hiding them by default simply made this feature underutilized.
2. Source will be displayed directly under the method method
   • This matches rubyapi.org's behaviour and makes a more natural experience. When viewing a method with long description, users won't need to click the toggle, and then scroll all the way down to see the source.
3. Clicking the method name will not toggle the source anymore. I made this change so we can later make clicking method names link to the methods instead, like rubyapi.org and many other language documentations do.

Demos

Before

Screen.Recording.2024-09-08.at.23.41.03.mov

After

Desktop

Screen.Recording.2024-09-09.at.11.30.14.mov

Mobile

Screen.Recording.2024-09-09.at.11.28.56.mov

[etiennebarrie]

3. Clicking the method name will not toggle the source anymore. I made this change so we can later make clicking method names link to the methods instead, like rubyapi.org and many other language documentations do.

Even if we decide to keep the source toggle on the method name, I'd love to get the URL on the method name so that at least we can right-click, copy link location and share that more easily.

[st0012]

Does this look good to you? (ofc, I'm not going to make all method names green)

Screen.Recording.2024-09-09.at.13.18.40.mov

[rwstauner]

These are great improvements, thank you!

[paracycle]

I think this looks great, but I have one concern.

If you look at the following screenshot from one of your After demos, can you tell me quickly which code section is the source and which one is a part of the docs?

IMO, we need a distinguishing background or border or something (a designer would know better than me) for the "source code" section that opens up.

[p8]

Maybe move the toggle to the bottom, so the toggle and the source code are closer together?
SDoc currently does this:

[st0012]

I think this looks great, but I have one concern.

That's a good point. I'll think about how to avoid the confusion.

Maybe move the toggle to the bottom, so the toggle and the source code are closer together?

Since it's been at the top for a long time, moving it to the bottom would require a huge change on users' behaviour. It's also not uncommon to see methods having very long description and examples in Ruby (e.g. Array#[], Array#fill...etc.), and IMO being able to click and see the source toggle without scrolling further down would be a better experience.

[st0012]

To help distinguishing source code blocks and example code blocks, I ended up choosing to add Example label to code blocks interpreted as Ruby:

Notes

• It's easier to add Source label but I feel it a bit repetitive when you just clicked Source and then see the shown block marked as Source again.
• Styling options are limited because the html of example code blocks are NOT controlled by the Darkfish generator but directly from RDoc. So if we were to change its html structure, it could break gems that use RDoc (e.g. SDoc)

[p8]

Styling options are limited because the html of example code blocks are NOT controlled by the Darkfish generator but directly from RDoc. So if we were to change its html structure, it could break gems that use RDoc (e.g. SDoc)

You should be able to change the background of the source with the following:

.method-source-code pre {
  background: #ebead5;
}

Also SDoc uses it's own css and templates, so it shouldn't be affected.
It uses rouge for code highlighting: rails/sdoc#239