Easy way to reach online documentation?

General Usage
1

This is one of those “what am I missing?” posts.

The function-based documentation of packages using ? at the REPL is, shall we say, inconsistently helpful. Most decent packages do have web documentation that ranges from good to indispensable. Very few, however, include direct links to it within the terminal-printed doc strings.

I find that I am constantly Cmd-Tabbing to the browser, hitting Cmd-L, and then typing until I match the bookmark I have made to the documentation home (possibly requiring some down-arrows to reach). This morning I finally conceded that this is the kind of annoying, repetitive task that I should automate.

It’s not hard to imagine doing so. I might be happy with the equivalent of (in a Mac-centric form):

module_pages = Dict( 
    :Pkg => "https://pkgdocs.julialang.org/",
    :Plots => "https://docs.juliaplots.org/latest/",
    :DataFrames => "https://dataframes.juliadata.org/stable/",
 )

help(s::Symbol) = run(`open $(module_pages[s])`)
help(m::Module) = help(Symbol(m))

Then help(:Pkg) gets me where I want to be. There are ways to tart that up, of course. But I wonder if other users have a simple process already that I’ve overlooked. Have I just been trapped at the wrong local minimum?

5 Likes
2

A cross platform enhancement might use GitHub - tpapp/DefaultApplication.jl: Julia package for opening a file with the default application determined by the OS.

2 Likes
3

Something else I would like to see is more use of the Extended Help mode for modules via ??.

4

Links can and should be written specifically indicating the minor version of the installed package, though. “Latest” and “stable” can change over time and you probably don’t want the package to have to update that string.

1 Like
5

I think something like Literate.jl/src/Literate.jl#L1-L7 should be used more often. Then you get the link from ?Literate.

5 Likes
6

As a new Julia user I have struggled with the lack of discoverability of information. Even when a package is installed you cannot use help unless it has been using-ed.

It would be nice if we could have local documentation for all our installed modules and packages that could be searched without loading first.

7

I’ve created a small package PkgOnlineHelp to try and help with this issue. From the README file:

A small package to help users navigate to Julia package home repositories. The two (identical) functions exported by this package are pkg_site and package_site.

`url = package_site(pkgname::AbstractString; autoopen=true)`

`url = pkg_site(pkgname::AbstractString; autoopen=true)`

Attempt to find the URL of a package’s home repository, by searching through the registries in DEPOT_PATH. If autoopen is true (default), then open the URL using the default browser.

Example

julia> package_site("StaticArrays")
"https://github.com/JuliaArrays/StaticArrays.jl.git"

In this example the web site is also opened in the user’s browser.

The package is in the wait period for registration. If you want to try it out now, it can be added using its URL: GitHub - simonp0420/PkgOnlineHelp.jl: Fast access from the Julia REPL to package documentation web sites

7 Likes
8

Update: I’ve added a lot more functionality, including a convenient @docs macro that can be called like

julia> @docs StaticArrays

Also added the ability for user to specify particular web sites to be opened when a package name or other keyword is passed to the @docs macro. These sites are stored in a permanent database so they are available in all future Julia sessions. See the updated README.md file for more details.

I will announce the package in another post once the registration period is complete.

9

@PeterSimon I really like the idea of giving better and easier access to a packages manual, I’ve often wished for it

At the same time, I wonder: how about extending the Project.toml specification to add some more (optional) fields:

  • homepage URL (may be distinct from repository)
  • documentation URL
  • a brief blurb describing what the package is about

Then your package could use it, or it could even be built into Julia / the package manager?

5 Likes
10

Sounds like a great idea to me. Maybe worth opening an issue?

Edit: Looks like there is already an issue that suggests similar additional metadata in Project.toml.

11

Not much progress on this issue, it would appear. :frowning: