Package documentation exploration

[ulugbekna]

This is an umbrella ticket to make exploring package documentation easier. There are several steps that can be taken (and should be discussed at some point):

1. Currently, the tree view has a button (see the screenshot) to open the documentation link indicated in a package's opam file (field doc). But there is no button if the doc field isn't indicated. We still, however, could offer generating the package doc ourselves and opening in the browser (or not - see below).

2. Integrate odig support in the plugin - this would allow much better ways to explore the documentation offline, hence faster and the desired package version

3. Allow opening the documentation in the vscode itself, which looks like this:

We can do this quite easily using odig, Live Preview extension by Microsoft, and maybe playing with workspaces.

4. Add a command OCaml: Show package documentation which would show a list of packages as a list and user can pick one.

It would be quite awesome to see 2 & 3 happen.

[tatchi]

Hi,

Like I said on Slack, I would love to work on that issue. I've played around with odig/odoc and created this quick POC:

https://user-images.githubusercontent.com/5595092/132959481-f43bd2e8-e77f-42b0-b875-675931c196bb.mov

But before going further, I would like to be sure we're aligned on the requirements and the way to move forward. Following our discussion on slack with @tmattio, I learned that there's an infrastructure that builds documentation. If I understand correctly, we could use that infra instead of odig/odoc. It would require users to have an internet connection though, so we were not sure if that would be a better idea? Note that even if we use the "offline" solution with odig/odoc, a user would still have to install these two packages at the time he wants to generate documentation (if they're not yet installed). If he doesn't have an internet connection at that time, he won't be able to generate the documentation.

Anyway, I guess the first question would be to decide on what solution to use to generate the documentation? Should we use (and require the user to install) odig/odoc, or should we leverage the infrastructure?

[tmattio]

This is great, thanks @tatchi!

If I understand correctly, we could use that infra instead of odig/odoc. It would require users to have an internet connection though, so we were not sure if that would be a better idea?

That's right. Depending on an internet connection is a huge constraint, so I think we should prefer other solutions. If we really want to use the doc infra, we'll need a fallback anyway, so the work you're doing with odig/odoc will be useful in any case.

a user would still have to install these two packages at the time he wants to generate documentation (if they're not yet installed).

That's fine to depend on an internet connection to install packages, but once they are installed, users should be able to work without one.

Also, the work you're doing should not take the installation of missing packages in scope IMO. If that's something we want to have, this can be done separately.

A few comments on the demo you've uploaded:

• Do you know how flexible we are on the design? I assume we could provide our own styling if needed? (I'm not familiar with odig)
• The documentation can be opened in a Webview in VSCode directly. The idea is that you can have your code and the corresponding documentation in your editor. See the screenshot @ulugbekna uploaded in the issue description.

[ulugbekna]

Thank you for taking initiative on this @tatchi!

I think in order to model precisely how the feature should look like, we need to know well capabilities and limitations of odig, doc website, and their integration with vscode. I am yet to get there, so below I will describe how I think think the feature should look like.

We should provide two separate ways to look up documentation: 1) offline with odig 2) online with docs website (docs.ocaml.org that is?)

By "separate" ways, I mean that the commands should be separate "Look up documentation (from the system)" and "Look up documentation (online)". I think having fallbacks-based workflow can be confusing for users: if sometimes the docs open offline and sometimes in browser, users will be perplexed. Such a workflow is also harder to design, maintain, and handle errors for. I think it also makes sense to have separate PRs for offline and online doc lookup.

The priority should be on offline workflow because it's faster, and users usually look up docs for packages that are already present on the system (odig can generate docs for installed packages only, afaik). Ideally, we would indeed have support for docs inside vscode (if the technical burden of implementation & dependencies is worth it) -- otherwise, there's little difference between looking up the docs with our extension and doing odig odoc pkgname.

We should also take into account that along with docs.ocaml.org, packages can have their own doc webpage, so users should be able to pick without confusion which doc page they want to open. We should do something with the doc lookup icon in the package view tree, ideally without being "smart" about it with fallbacks and stuff to not confuse users.

@tatchi , does this make sense for you to have a good offline-first docs lookup with odig PR?

If the user doesn't have odig & odoc, we should show a message to install them.

[rgrinberg]

Is there a way to avoid running odig/odoc and fetch a documentation tarball instead? The requirement to install a package before browsing the doc with odig really damages the usability with a package manager like opam.

[tatchi]

Also, the work you're doing should not take the installation of missing packages in scope IMO. If that's something we want to have, this can be done separately.

Agreed. My idea was to add that feature only for packages we already show under the sandox view.

• Do you know how flexible we are on the design? I assume we could provide our own styling if needed? (I'm not familiar with odig)

It seems that odig has some built-in themes: https://github.com/b0-system/odig#sample-odoc-api-documentation-and-manuals. I think it should be possible to create a custom one too: https://b0-system.github.io/odig/doc/odig/packaging.html#theme_install

• The documentation can be opened in a Webview in VSCode directly. The idea is that you can have your code and the corresponding documentation in your editor. See the screenshot @ulugbekna uploaded in the issue description.

Yes, that's definitely something I was planning to try implementing. There's also a Webview API that might be worth exploring.

The priority should be on offline workflow because it's faster, and users usually look up docs for packages that are already present on the system (odig can generate docs for installed packages only, afaik)

I agree, that PR will focus on the offline workflow 👍

We should do something with the doc lookup icon in the package view tree, ideally without being "smart" about it with fallbacks and stuff to not confuse users.

My idea was to keep the current icon (and its behaviour) as is and add a new icon for the offline doc. Does that sound good?

[tatchi]

Is there a way to avoid running odig/odoc and fetch a documentation tarball instead? The requirement to install a package before browsing the doc with odig really damages the usability with a package manager like opam.

I'm not sure I understand what you mean. As @ulugbekna said, the idea of this PR is to focus on the offline mode (and only for packages that are installed).

[rgrinberg]

Sure, I can clarify what I mean. The goal of this ticket is stated to be:

This is an umbrella ticket to make exploring package documentation easier.

A major barrier to exploring a potential package is having to build the package. This process is both slow and can destroy your switch. This is about the only reason that I use online docs at all - even though I'm in full agreement with others in this thread pointing out that they are generally inferior to offline documentation.

For that reason, a wrapper for odig inside vscode does not excite me. I'm obviously not against it, as it adds some minor convenience over running the command manually. But the issue of accessible documentation will remain even with this feature.

[tatchi]

Thanks for the clarifications @rgrinberg. I agree that having a wrapper around odig to generate the documentation probably won't solve the general issue of accessible documentation.

Should I still continue to work on the offline doc generation with odig and eventually create a separate issue for it? Or do you prefer taking more time to re-think the whole accessible documentation story? cc @tmattio @ulugbekna

[rgrinberg]

Should I still continue to work on the offline doc generation with odig and eventually create a separate issue for it

Nothing wrong with integrating odig with the plugin. Some people like this tool as far as I can tell, therefore it makes sense to offer support for it.