Documenter.jl: Support both live and static documentation deploying setups in the "edit this page" links

[waldyrious]

As discussed in https://github.com/JuliaLang/julia/pull/18588#issuecomment-265740359, it would be nice if Documenter supported a way to set the "edit this page" links to point to a given branch (e.g. master by default) instead of pointing to specific commit references. For instance, at the moment the edit link at this page in the Julia documentation points here.

If the project using Documenter isn't set up to automatically deploy docs on every push, then linking to master rather than the specific commit would mean that the text seen in the rendered documentation might not match the doc sources. On the other hand, it is a bit counter-intuitive to have a link named "edit this page" pointing to a snapshot of a page which by definition isn't editable (and in Github's interface the edit button indeed is disabled in those cases). Because of this, I suppose in the end it might be necessary to provide a source branch for the docs build process regardless, in order to support both the live and the "static" cases -- with the difference being that release branches would normally be pretty stable and rarely change.

Otherwise (i.e. if no branch is provided/assumed), the links should probably be changed to say "view source" rather than "edit". But I'm just guessing -- there may well be more flexible ways to handle this.

[MichaelHatherly]

Thanks for writing this up @waldyrious.

[simonbyrne]

I didn't realise there was an issue for this when I opened https://github.com/JuliaLang/julia/issues/20870.

I think it would be worth having both a "source" link which links to the commit, and an "edit latest" link, which just gives a best guess to point to the development branch.

[fredrikekre]

Seems like this is possible now? From the docs

html_edit_branch specifies which branch, tag or commit the "Edit on GitHub" links point to. It defaults to master. If it set to nothing, the current commit will be used.

[mortenpi]

Yep, I believe this specific issue was solved by html_edit_branch in #581 (also, ref #580). The edit links in the manual, including the stdlib ones, seem to behave reasonably. Feel free to reopen if there's something that was overlooked.

[waldyrious]

@mortenpi I haven't tried this myself, but doesn't

If it set to nothing, the current commit will be used.

...mean that these bits of the opening comment above:

it is a bit counter-intuitive to have a link named "edit this page" pointing to a snapshot of a page which by definition isn't editable (and in Github's interface the edit button indeed is disabled in those cases).

if no branch is provided/assumed, the links should probably be changed to say "view source" rather than "edit".

...are still unadressed? If so, that should probably be a separate issue.

[mortenpi]

Ah, yes, I missed that. No, the text wont change at the moment, but we could definitely consider having the link say "view" when html_edit_branch == nothing.

[fredrikekre]

Perhaps it could always say Source. Wouldn't that be accurate in bit cases?

[waldyrious]

@fredrikekre I'd rather have an explicit label, both because it provides more information, and because it encourages readers to collaborate when there's the option.

@mortenpi should I open an issue for that?

[fredrikekre]

Perhaps I am missing something, but when do you want to end up on the uneditable raw markdown page?

[waldyrious]

when do you want to end up on the uneditable raw markdown page?

As a user I'd say never -- to clarify, I was referring to

pointing to a snapshot of a page which by definition isn't editable (and in Github's interface the edit button indeed is disabled in those cases)

Note for example how the edit icon is disabled in https://github.com/JuliaDocs/Documenter.jl/blob/6abfaeee9f488f0487a022551634807daf4c2515/README.md, and shows the tooltip "You must be on a branch to make or propose changes to this file".

Did I misunderstand Documenter's behavior? Does the link actually point to the raw source, rather than to snapshots like the one above, when html_edit_branch == nothing?