Description
PkgOnlineHelp is a small package that enables browsing to package documentation sites or other web sites by entering just a few keystrokes at the REPL. It addresses the problem mentioned in this thread where one often needs to refer to web-based documentation that is more detailed than the “doc string” help already available at the REPL.
Usage
The main convenience macro provided by the package is @docs. Here is an example of usage:
julia> using PkgOnlineHelp # If not included in your startup.jl
julia> @docs StaticArrays
"https://github.com/JuliaArrays/StaticArrays.jl.git"
The StaticArrays repo site is returned and opened in the browser. By default, when invoked with a package name as shown above, @docs will return and open the package’s repo web site. However, this site choice can be overridden via a call to add_pkg_docs as shown below. In the above case, the repo site was determined by searching through all Julia registries in DEPOT_PATH, implying that unregistered packages will not be found, by default.
However, @docs can also be used to access unregistered packages or even arbitrary web sites. For example, suppose you wish to have rapid access to the portion of the online Julia documentation discussing macros. Then you would enter (one time only) the following at the Julia prompt:
julia> add_pkg_docs("macros", "https://docs.julialang.org/en/v1/manual/metaprogramming/#man-macros")
Later in this Julia session, or in any future session, the site can be quickly opened by entering
julia> @docs macros
Of course, this example assumes that using PkgOnlineHelp has already been entered.
Similarly, entering
julia> add_pkg_docs("StaticArrays", "https://juliaarrays.github.io/StaticArrays.jl/stable/")
will cause future invocations of @docs StaticArrays to open the hosted documentation for the package, rather than the repo site.
Each call to add_pkg_docs adds an entry to a tiny TOML database file stored in a Scratch space, providing permanence across Julia sessions.
The contents of the PkgOnlineHelp database can be shown by typing list_pkg_docs() at the REPL prompt. Items can be removed using, e.g. remove_pkg_docs("macros").
Discussion
I expect that eventually a similar capability will be incorporated directly in Julia or its package manager. In the meantime, this is my modest attempt to give back something of general utility to the Julia community. Enjoy! – Peter