GUI HTML browser for documentation

[mgkuhn]

MATLAB has a very nice command doc that starts a browser to display the manual, either the front page, or the man page of any specified function. I just had a go at drafting an equivalent doc() function for Julia, because I very much would like to have easy off-line access to the HTML documentation of both Julia and any packages in the current environment:

• Some people may want to use Julia in places without practical Internet access (“in the field”, “on the far side of the moon”, etc.).
• Online documentation found via Internet search may not be about the software version currently used locally (which may in particular become an issue once Julia is more commonly used installed from Linux distributions).
• I think there is a general expectation that software comes with documentation included locally, and that users are first pointed at the local documentation, rather than some web site.

Before I turn this into a first PR, I'd like to some feedback, e.g. on

• where in the code base this should go
• what existing standards (file naming conventions, etc.) and mechanisms (index files or data structures) there are already to locate local HTML documentation of objects in packages

I'd hope such a doc() function can one day replace the current URL in the banner.

As a prerequisite, Julia first needs a function hasdesktop() to query if the current process has access to a GUI desktop (otherwise it makes no sense to try starting a web browser), and a function browse_url() to fire up a GUI web browser and show a provided URL. Both these functions are obviously highly platform specific, but I think I have now working solutions for Linux/Unix, Windows and macOS. (UPDATE: these functions are now in a registered new package Desktop.jl)

It then needs to locate the relevant HTML page on the local disk (across a range of different installations or build environments), or figure out a likely online location as a fallback if no suitable page can be found on the local file system. The code below currently does this only for the main manual, the HTML source of which is already part of the standard Julia distributions.

Any ideas/suggestions on how to best do this for the local HTML manuals of Base and stdlib, which are usually also pre-installed already?

And what about obtaining or building and caching local HTML documentation for installed packages? These are today normally installed by Pkg.jl without any HTML documentation included.

#!/usr/bin/env julia
using Base.Filesystem
using Desktop

manual_index = nothing

function isrelativeurl(url)
    if occursin(r"^(https?|ftp|file|mailto):/"i, url) ; return false ; end
    return !isabspath(url)
end

"""
Search for the URL of the main index.html page of the Julia manual
and store it in global variable `manual_index`.
"""
function doc_init()
    paths = [
        "../share/doc/julia/html/en/index.html",
        "../../doc/_build/html/en/index.html",
        "https://docs.julialang.org/en/v$(VERSION.major).$(VERSION.minor)/"
    ];
    for i in eachindex(paths)
        if isrelativeurl(paths[i])
            paths[i] = joinpath(Sys.BINDIR, paths[i]);
            if !isfile(paths[i])
                continue
            end
            global manual_index = "file://" * realpath(paths[i])
            return
        else
            manual_index = paths[i]
            return
        end
    end
    @error "Cannot find Julia HTML documentation in " * join(paths, ':')
end

"""
    doc()

Open the Julia documentation in a web browser.

This currently only opens the front page of the Julia manual.
(Hopefully, a future version of this function will also use an index of
all documentation strings shown in the manual of Julia or any
installed packages to get to the right page for any available package,
module, function, method, constant, etc., to give users maximum offline
access to the HTML documentation.)

See also: [`@doc`](@ref), [`browse`](@ref), [`hasdesktop`](@ref)
"""
function doc()
    if manual_index === nothing ; doc_init(); end
    if !(hasdesktop() && browse_url(manual_index))
        print("Use a web browser to look at\n$manual_index\n")
    end
end

# basic demo
doc_init()
doc()

[inkydragon]

where in the code base this should go

Maybe a separate pkg? Or open a Juleps (Julia Enhancement Proposals) and add it to stdlib.

Another idea: if you want to handle installed pkg, you need information from pkg system.
The best way to do that is when you add a new pkg, we collect information and add those information into a database. Or Ask developer to provide those information as a part of pkg metadata.

what existing standards (file naming conventions, etc.) and mechanisms (index files or data structures) there are already to locate local HTML documentation of objects in packages

I guess most pkg use Documenter.jl to generate docs, you may have a look at it.

---

Update:

• Zeal - Offline Documentation Browser

[mgkuhn]

I have now released Desktop.jl, a package based on the parts (originally contained) in the above example code that implement basic GUI desktop interactions:

• open a URL with a web browser,
• open a file with its default application,
• test if the current process has access to a desktop.

I guess these functions ought be moved into InteractiveUtils if doc() is to be part of the out-of-the-box experience of Julia.

I also found DocSeeker.jl, a package to tries to find documentation for a package.

using Desktop
using DocSeeker
open_file(DocSeeker.docsdir("DocSeeker"))

[mgkuhn]

One problem with my vision of easy local access to HTML documentation for every installed Julia package is that it seems currently not customary to install HTML documentation of packages locally.

The auto-generated HTML files are not (supposed to be) committed to the git repo of a package, and it also isn't customary to build the HTML package documentation locally when a package is installed (which would require Documenter and takes some time). This is in contrast to Julia itself, where the HTML documentation (manual, base, stdlib) comes with the download tarball.

Is there any practical way in which Pkg could one day download pre-built HTML documentation for each package?

[timholy]

Is there any practical way in which Pkg could one day download pre-built HTML documentation for each package?

Presumably one could download it from the gh-pages branch of the package. I don't know much about this, however.

Just checking, are you aware that Juno has an excellent built-in documentation viewer?

[mgkuhn]

Presumably one could download it from the gh-pages branch of the package.

That sounds like a good idea. We would need a convention for tagging compiled HTML documentation stored in a separate branch (e.g. gh-pages). For example, if the HTML documentation build for package release v1.0 is tagged html1.0 (and the PDF documentation pdf1.0, if any), then Pkg could easily download ready-build documentation for each package release from the same repository as the source code. Such a tagging convention ought to be added to Documenter.deploydocs.

[mgkuhn]

Just checking, are you aware that Juno has an excellent built-in documentation viewer?

Yes, that works wonderfully if you just want to look up the content of a docstring associated with some object (function, type). But what about the front pages, introductions, tutorials, larger use-case examples and appendices, i.e. all the parts of the documentation that a first-time user will be most interested in to get an overview of the entire package? That is all missing if you can only lookup docstrings based on the identifiers of the objects they describe. That introductory part of the information is currently not easily available offline (and in a way that automatically matches the installed package version).

[ViralBShah]

#44537 is not the same as this, but would go a long way in making more extensive documentation (like the manual) be available to users locally.

[BeastyBlacksmith]

I would be against the bloat of having the html version of every installed package version on my machine by default.

What would be great would be if there is a way to conveniently retrieve that documentation for later reference. I'd imagine that to live in Pkg.jl, so I could do

pkg> doc Example

which would download the documentation to e.g. .julia/doc/Example/vX.Y if not present and then open it locally.
This should be automatically cleaned up every now and then just like artifacts are.

[ViralBShah]

I am going to recommend that this can easily be implemented as a package and we can use discourse for further discussion.