Add "collapse/expand" functionality

[Hetarth02]

• Add "collapse/expand all" functionality with a icon in navbar
• Add "collapse/expand" functionality to sensible individual element
• This PR aims to close Add "collapse/expand all" functionality #1393.

Recording.2023-03-18.163946.mp4

[Hetarth02]

@mortenpi I tried creating another branch as per the discussion in #2065 but it still displays all of the commit history. So, once again to clarify for anyone looking at this PR please check the Files changed menu.

[mortenpi]

I really like this! It makes these long docstring lists readable. And the open/close animation feels pretty smooth.

A couple of thoughts though. What do you think about the following:

• Having the collapse/expand all button be the rightmost item in the top bar?
• Could we try a variant where the docstring collapse/expand button is also on the top-right of the docstring?
• I am wondering if we should have them be collapsed by default?
• We should do a demo build of the Julia manual with this.

[inkydragon]

https://www.mathworks.com/help/matlab/ref/sin.html

1. Having the collapse/expand all button be the rightmost item in the top bar?

Agree.
Would it be clearer to use text + icons? Just like Matlab doc ①.

2. Could we try a variant where the docstring collapse/expand button is also on the top-right of the docstring?

For document strings, we can modify the collapsed style, the cursor style when the mouse is selected (③), and also add hint text to highlight that this is a collapsed area that can be clicked to interact with.

3. I am wondering if we should have them be collapsed by default?

Maybe collapse by default for automatically generated doc str.
We can also add a keyword argument to control the default collapse behavior.

4. We should do a demo build of the Julia manual with this.

I would say that even though I've done it many times, building julia's documentation is still a bit complicated. Maybe try building the documentation for Documenter.jl first.

[Hetarth02]

@mortenpi

I really like this! It makes these long docstring lists readable. And the open/close animation feels pretty smooth.

Thanks!

• Having the collapse/expand all button be the rightmost item in the top bar?

The thing is when in responsive mode the side-menu button will be the last.

• Could we try a variant where the docstring collapse/expand button is also on the top-right of the docstring?

I think we can do that, but the problem then would be when a large name comes it will mess up the design.

• I am wondering if we should have them be collapsed by default?

Personally I would want them to be expanded, but I am fine with either.

• We should do a demo build of the Julia manual with this.

I tried but had some issues in generating one. I removed some parts from the julia library to mitigate the errors and was successfully able to build a partial working site. The video I have attached above is the same site I built locally.

[Hetarth02]

@inkydragon

Would it be clearer to use text + icons? Just like Matlab doc ①.

The thing is we don't have much space in the navbar or the docstring title on smaller devices. It is much likely to break the UI on smaller devices when we have text + icons combination.

We can also add a keyword argument to control the default collapse behavior.

Yeah, this is a good idea.

[mortenpi]

The thing is when in responsive mode the side-menu button will be the last.

That just hopped on the other side though, so it's not a problem anymore 🙂 #2076

I tried but had some issues in generating one. I removed some parts from the julia library to mitigate the errors and was successfully able to build a partial working site. The video I have attached above is the same site I built locally.

I didn't realize that it was already showing the Julia manual 🤦 I'm happy to look into doing the full build though. The errors might be due to some changes we've had on master here.

Personally I would want them to be expanded, but I am fine with either.

Let's leave them expanded for now then. Adding a per-block option is a good idea. We could also have a per-page option via an at-meta block. But let's do those in a follow-up PR -- let's not make this PR too complicated.

The thing is we don't have much space in the navbar or the docstring title on smaller devices. It is much likely to break the UI on smaller devices when we have text + icons combination.

I tend agree with this. I think we're kinda forced to go with icons right now.

I think we can do that, but the problem then would be when a large name comes it will mess up the design.

That is fair. I feel that maybe we should follow Matlab's lead here though and have the collapsed icon be > and expanded v.

For document strings, we can modify the collapsed style, the cursor style when the mouse is selected (③), and also add hint text to highlight that this is a collapsed area that can be clicked to interact with.

Yeah, some hover and cursor stuff might be worth trying out.

[Hetarth02]

It auto-closed the PR when I synced my fork. I have reopened the PR. Sorry for this!

[Hetarth02]

• Cursor will be a pointer when hovering over article header.
• Shifted the Nav-bar toggle to last position
• Changed the > as a indication instead of ^ for articles(kept the Nav-bar icons as it is)

[Hetarth02]

I'm happy to look into doing the full build though. The errors might be due to some changes we've had on master here.

@mortenpi If possible can you do this and check if everything works fine or are there any changes needed?

[mortenpi]

Awesome, this is great! Sorry for the delay, but I think this is nearly good to go if you're done with it.

• Just some minor suggestions in other comments.
• Could you add a CHANGELOG entry for this?

In principle, the JS code seems to have some duplication (e.g. the expand/collapse strings), so it could probably be refactored a bit to make it a bit cleaner. But that's pretty minor and not very important here, so more than happy to merge as is.

[mortenpi]

Here's a full Julia manual build: http://mortenpi.eu/juliadocs-demos/pr-2078-julia-manual-demo/

[mortenpi]

Thanks a lot for iterating on this @Hetarth02!