Suggestion for package docstrings

General Usage
1 
"""
    Package MyPackage v$(pkgversion(MyPackage))

MyPackage does this and that, and this text can be the the same as the "About" on it's github page.

Docs under https://mypackageauthor.github.io/MyPackage.jl/
$(isnothing(get(ENV, "CI", nothing)) ? ("\n" * "Package local path: " * pathof(MyPackage)) : "")
"""
module MyPackage

# MyPackage contents
end # MyPackage

Now, on typing

help?> MyPackage

this will produce like following:

search: MyPackage 

  Package MyPackage v1.0.0

  MyPackage does this and that, and this text can be the the same as the "About" on it's github page.

  Docs under https://mypackageauthor.github.io/MyPackage.jl/

  Package local path: /Users/mypackageauthor/.julia/packages/MyPackage/kWCpa/src/MyPackage.jl

Many (majority?) of the packages do not provide the package docstring. Then, on help for package (like above), Julia would print the whole Readme. This is seldom really helpful, and especially if Readme is the actual full documentation, the output into the REPL can be overwhelming.

The docstring according to the template above is very easy to produce, and would inform the user on most basic things about the package. A Ctrl/Cmd click onto the link (in VSCode, at least) would immediately take you to the online docs for all further questions.

What do you think?

3 Likes
2

I actually like the READMEs being printed for packages as long as they’re not too long, but a small message like this is good too.

1 Like
3

For packages that do not provide a docstring PkgOnlineHelp is a useful workaround.

1 Like
4

Just a few days ago, I wrote a Perl script that does a very similar thing. I called it jj for Julia Jump, and:

  • If you pass it a package name, it’ll open a browser tab to the github repo for that Julia package.
  • If you pass it no args, and:
    • (you have a tty), use fzf to let you autocomplete a Julia package name.
    • (you don’t have a tty), use dmenu to let you autocomplete a Julia package name.

It’s kind of Linux/X11-centric, because that’s what I use, but it’s very similar in spirit to your PkgOnlinehelp.jl . I will definitely check your package out.

I imagine you use it a lot, because I use my own script a lot now that I have it.

Maybe I’ll share my own script later, but it’s kind of a quick and dirty hack, and I’d like to clean it up first.

1 Like