Better live docs

[fonsp]

New discussion page

We created https://github.com/JuliaCommunity/live-docs-discussion/discussions as a dedicated place to discuss Pluto's Live Docs feature, and future ideas for Julia's documentation in general! Take a look!

---

Some improvements:

• Show what is currently being searched for
• Support cross-reference links between docs
• Show that it is searching
• Title of the docs should be a textbox where you can enter a query directly
• Handle dots, like Module.funky
• Function arguments
• Show when the name is found but it has no docs
• To the right of a cell might make more sense
• Heuristics for which function is dispatched on - can VS Code do this nowadays? I guess that we can do this dynamically, since some of the types are known
• Popup docs don't work for some symbols #832 (comment)
• Popup docs don't work for some symbols #832 (comment)

Extras:

• apropos(str) might be useful. Is resource intensive though, maybe write our own version that just returns the first hit? Although that might not be the most relevant one
• Show filename and line number of defintion. Double cool if it is a clickable link to GitHub! (Like in methodtables shown as text/html) I found this useful when the docs are unclear or when you want to know how something works.

What is Julia's doc system missing? CLIPPY

• Given an object, tell you what you can do with it. In OOP languages this is obj.<TAB> to autocomplete.

Please post other ideas and suggestions!

[ilyagr]

Given an object, tell you what you can do with it. In OOP languages this is obj. to autocomplete.

The simplest thing to do is to show the docs for typeof(x) when there are no useful docs for x.

The next step might be to find a way to show methodswith(typeof(x); [supertypes=true]) together with the docs for typeof(x). The output is kind of long to put into the Live Docs screen, but if you make it a tree based on which module different methods come from, it could be OK.

One problem is that adding supertypes=true is helpful for some types and harmful for others. Perhaps you could show supertypes(typeof(x)) if it's non-trivial. If the user clicks on one of the supertypes, you could show methodswith for that supertype.

[fonsp]

Thanks! Perhaps as an experiment, you could take an existing notebook, and run the methods that @ilyagr suggested and see if the results would be helpful.

[fonsp]

About autocompleting functions that can be dispatched on something: https://discourse.julialang.org/t/why-is-multiple-dispatch-a-feature/31101/10?u=pfitzseb

[fonsp]

(Hiding the above conversation because it is resolved by 744e002)

[lungben]

One more wish:
Currently, when the notebook is busy executing a cell, the Live Docs are not displayed. It would be great if the Live Docs are always available, so that I can use the time waiting for a cell to be finished to look up info for writing the next cell.

[fonsp]

I don't think that we can get docs if the process is busy.

[danvinci]

Might make sense to add a ''go back'' arrow?

I often find myself going down a rabbit hole of 3-4 levels, might be useful keeping track of the last 5 items visited or whatever makes more sense UI and performance-wise.

[KristofferC]

JuliaLang/julia#38791 is related.

[fonsp]

New discussion page

We created https://github.com/JuliaCommunity/live-docs-discussion/discussions as a dedicated place to discuss Pluto's Live Docs feature, and future ideas for Julia's documentation in general! Take a look!