Plea to package developers regarding documentation!

Very serious topic ahead:

Please please please can package developers put a link BACK to the source repo inside your documentation! Without it, the documentation becomes a trap.

Randomly selected example: https://juliastats.org/StatsBase.jl/stable/

It is becoming more common now that Google is taking me to documentation pages rather than the Github repo. I frequently flip back and forth between code and documentation, but this process is beyond cumbersome if the documentation contains no easily accessible link to the code with which it is associated. Links are free to use!

12 Likes

I agree this is annoying, but it looks like there is already a work-in-progress PR for Documenter to add this: https://github.com/JuliaDocs/Documenter.jl/pull/1254! I think that’s a good solution since it’ll help everyone instead of each package needing to add a link manually.

13 Likes

Ha! I had no idea. I suppose adding it in Documenter is maybe a good approach going forward, but it is a pretty low (one time!) cost to do so anyway.

Most packages start out like the linked example:

StatsBase.jl is blah blah blah…

Why not just turn that into a link to the repo?

In the bottom of every docstring in the documentation there is a button labeled “source” which takes you straight to the source code of that function.

3 Likes

Yea that isn’t really what I want though. I just want to go to the repo.

1 Like

I usually put a badge like this GitHub commits since tagged version in README with

[![GitHub commits since tagged version](https://img.shields.io/github/commits-since/USER/PACKAGE.jl/vX.Y.Z.svg?style=social&logo=github)](https://github.com/USER/PACKAGE.jl)

and then use it as the docstring of the module by this one-linear

@doc read(joinpath(dirname(@__DIR__), "README.md"), String) PACKAGE

so that the badge is included in the documentation (e.g., https://tkf.github.io/BangBang.jl/dev/#BangBang.BangBang). I like that it provides useful bits of information while also providing the link to the repository (though it relies on that people already know that badges are often clickable).

For fun, you can find other github-related badges in https://shields.io/ (type github in the search form).

3 Likes

you can just google: github package.jl.
just let google know you are interested with github

You can usually just press the “Edit on GitHub” button in the top right. It takes you to the repo.

3 Likes

It usually takes you to the gh-pages branch of the repo, so one should make additional click to switch to the main page of the repository. It’s not a big issue, but it is annoying when you do it 100th time.

As a side note, it can be a small fix of the corresponding PkgTemplates template also.

1 Like

Browser tabs?

1 Like