Links to source not shown in JuliaImages docs

JuliaImages / juliaimages.github.io

Documentation For JuliaImages

https://juliaimages.org

33 stars 56 forks source link

Links to source not shown in JuliaImages docs #179

Closed JeffFessler closed 3 years ago

JeffFessler commented 3 years ago

The JuliaImages documentation is very nice but it seems to lack the blue rectangular links to the "source" code that appear in most (Documenter generated?) docs. I am a bit perplexed why they are missing because I thought Documenter did that automatically. I would make a PR if I could, but I couldn't figure out from the Documenter docs how one controls visibility (or not) of source code links. It's probably a one line change in make.jl for someone who knows the magic incantation...

johnnychen94 commented 3 years ago

I'm not sure if I understand what "the blue rectangular links" is. Do you mean the "Edit on Github" button? Or could you provide an link/example where this is missing?

JeffFessler commented 3 years ago

For a "typical" Documenter output viewed in html in a browser like this: https://jefffessler.github.io/MIRT.jl/dev/reference/ if you hover your mouse in the bottom right of the documentation area for a function then a light blue rectangle appears with the word "source" in it that is a url that goes to the source code. I'll try to paste a picture in the next comment box. (Personally I think it would be more clear if this link were always visible instead of only appearing when hovering, but that is a different issue.) Actually I don't know if this feature is in the html produced by Documenter or if it is some magic that github is doing. But I have seen it in most Julia packages, but not in JuliaImages for some reason. Here's a specific place where it is missing: https://juliaimages.org/stable/function_reference/#ImageMorphology.thinning

JeffFessler commented 3 years ago

johnnychen94 commented 3 years ago

Oh right. This button seems to appear only when the source code folder /src is placed at exactly the same repository.

For the juliaimages.github.io, we build the documentation in a separate repository so that package source codes are minimized (when user installs Images, they don't download the docs). Since Documenter can't figure out what the correct URL source is, it doesn't display the link button (IIUC).

Personally, I'd use @which macro to find out where and what the method is.

julia> @which thinning
ImageMorphology

and then I'll search thinning using github's search engine in the ImageMorphology repo.

Looks like there's nothing we can do here, so I'll just close this issue. If you have any further thoughts about the "reference page", I can reopen it or we could discuss it in a new issue.

JeffFessler commented 3 years ago

Thanks for looking into it. I've looked more at Documenter "issues" and it seems that others would also like to have the blue source button point to related repos: https://github.com/JuliaDocs/Documenter.jl/issues/1273 https://github.com/JuliaDocs/Documenter.jl/issues/1325 So for now we wait until such issues are resolved. Thanks again.