Improve method source toggling

st0012 commented 2 months ago

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.
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.
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

https://github.com/user-attachments/assets/ca68c0d0-147b-421f-9e04-904366856daf

After

https://github.com/user-attachments/assets/ea6ed17f-930a-4d4e-a298-79a535c94abc

etiennebarrie commented 2 months ago

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 commented 2 months ago

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

https://github.com/user-attachments/assets/e0ba6324-deaa-4e49-ae58-5d187796d6b1

paracycle commented 2 months ago

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 commented 2 months ago

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

st0012 commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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: https://github.com/rails/sdoc/pull/239

st0012 commented 1 month ago

I decided to go with @p8's suggestion to use a different background color for the source code block (see the updated demo vid) because it introduces less complexity.

p8 commented 1 month ago

Looks great!

colby-swandale commented 1 month ago

I have a couple of items:

The various yellows on the page doesn't seem to blend well together and makes the page distracting. Could we tweak the colors a bit to make it easier on the eyes?

The arrow/collaspe icon next to the Source link is a bit confusing to me. It comes across as a play button for audio/video nearly everytime I look at It. Could we look to remove it and give the link an active/hover state?

st0012 commented 1 month ago

I made their color match and change it to fit the current color scheme better:

I'm not happy with the color but I think further improvements on it belongs to #1164

Could we look to remove it and give the link an active/hover state?

I think this is more subject to personal taste? To me it's a clear sign that it's a details element and I can expand it. It's the default triangle that comes with the element and it's in the sidebar too.

I don't mind it being redesigned later but I don't see the value of introducing yet another UI effect to remind users it's click/expandable.

st0012 commented 1 month ago

@colby-swandale Can you give this another look please?

ruby / rdoc