Deprecate edit_branch in favor of edit_link (#1173)

CHANGELOG.md

@@ -18,6 +18,10 @@
 
   **Possible breakage:** Packages overriding the default Documenter CSS file, relying on some external CSS or relying on Documenter's CSS working in a particular way will not build correct-looking sites. Custom themes should now be developed as Sass files and compiled together with the Documenter and Bulma Sass dependencies (under `assets/html/scss`).
 
+* ![Deprecation][badge-deprecation] ![Enhancement][badge-enhancement] The `edit_branch` keyword to `Documenter.HTML` has been deprecated in favor of the new `edit_link` keyword. As a new feature, passing `edit_link = nothing` disables the "Edit on GitHub" links altogether. ([#1173][github-1173])
+
+  **For upgrading:** If using `edit_branch = nothing`, use `edit_link = :commit` instead. If passing a `String` to `edit_branch`, pass that to `edit_link` instead.
+
 * ![Feature][badge-feature] Deployment is now more customizable and thus not as tied to Travis CI as before. ([#1147][github-1147], [#1171][github-1171])
 
 * ![Feature][badge-feature] Documenter now has builtin support for deploying from GitHub Actions. Documenter will autodetect the running system, unless explicitly specified. ([#1144][github-1144], [#1152][github-1152])
@@ -470,6 +474,7 @@
 [github-1153]: https://github.com/JuliaDocs/Documenter.jl/pull/1153
 [github-1166]: https://github.com/JuliaDocs/Documenter.jl/pull/1166
 [github-1171]: https://github.com/JuliaDocs/Documenter.jl/pull/1171
+[github-1173]: https://github.com/JuliaDocs/Documenter.jl/pull/1173
 
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl

src/Utilities/Utilities.jl

@@ -663,6 +663,28 @@ function display_dict(x)
     return out
 end
 
+"""
+    struct Default{T}
+
+Internal wrapper type that is meant to be used in situations where it is necessary to
+distinguish whether the user explicitly passed the same value as the default value to a
+keyword argument, or whether the keyword argument was not passed at all.
+
+```julia
+function foo(; kwarg = Default("default value"))
+    if isa(kwarg, Default)
+        # User did not explicitly pass a value for kwarg
+    else kwarg === "default value"
+        # User passed "default value" explicitly
+    end
+end
+```
+"""
+struct Default{T}
+    value :: T
+end
+Base.getindex(default::Default) = default.value
+
 include("DOM.jl")
 include("MDFlatten.jl")
 include("TextDiff.jl")

src/Writers/HTMLWriter.jl

@@ -7,7 +7,7 @@ A module for rendering `Document` objects to HTML.
 [`Documenter.makedocs`](@ref): `authors`, `pages`, `sitename`, `version`.
 The behavior of [`HTMLWriter`](@ref) can be further customized by setting the `format`
 keyword of [`Documenter.makedocs`](@ref) to a [`HTML`](@ref), which accepts the following
-keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_branch` and
+keyword arguments: `analytics`, `assets`, `canonical`, `disable_git`, `edit_link` and
 `prettyurls`.
 
 **`sitename`** is the site's title displayed in the title bar and at the top of the
@@ -53,6 +53,7 @@ import ...Documenter:
     Utilities,
     Writers
 
+using ...Utilities: Default
 using ...Utilities.JSDependencies: JSDependencies, json_jsescape
 import ...Utilities.DOM: DOM, Tag, @tags
 using ...Utilities.MDFlatten
@@ -245,8 +246,11 @@ an error and exit if any of the Git commands fail. The calls to Git are mainly u
 gather information about the current commit hash and file paths, necessary for constructing
 the links to the remote repository.
 
-**`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.
+**`edit_link`** can be used to specify which branch, tag or commit (when passed a `String`)
+in the remote repository the "Edit on ..." links point to. If a special `Symbol` value
+`:commit` is passed, the current commit will be used instead. If set to `nothing`, the
+link edit link will be hidden altogether. Default value is `"master"`, making the edit link
+point to the master branch.
 
 **`canonical`** specifies the canonical URL for your documentation. We recommend
 you set this to the base url of your stable documentation, e.g. `https://juliadocs.github.io/Documenter.jl/stable`.
@@ -312,7 +316,7 @@ their absolute URLs, can be included with the [`asset`](@ref) function.
 struct HTML <: Documenter.Writer
     prettyurls    :: Bool
     disable_git   :: Bool
-    edit_branch   :: Union{String, Nothing}
+    edit_link     :: Union{String, Symbol, Nothing}
     canonical     :: Union{String, Nothing}
     assets        :: Vector{HTMLAsset}
     analytics     :: String
@@ -324,22 +328,37 @@ struct HTML <: Documenter.Writer
     function HTML(;
             prettyurls    :: Bool = true,
             disable_git   :: Bool = false,
-            edit_branch   :: Union{String, Nothing} = "master",
+            edit_link     :: Union{String, Symbol, Nothing, Default} = Default("master"),
             canonical     :: Union{String, Nothing} = nothing,
             assets        :: Vector = String[],
             analytics     :: String = "",
             collapselevel :: Integer = 2,
             sidebar_sitename :: Bool = true,
             highlights :: Vector{String} = String[],
             mathengine :: Union{MathEngine,Nothing} = KaTeX(),
+            # deprecated keywords
+            edit_branch   :: Union{String, Nothing, Default} = Default(nothing),
         )
         collapselevel >= 1 || throw(ArgumentError("collapselevel must be >= 1"))
         assets = map(assets) do asset
             isa(asset, HTMLAsset) && return asset
             isa(asset, AbstractString) && return HTMLAsset(assetclass(asset), asset, true)
             error("Invalid value in assets: $(asset) [$(typeof(asset))]")
         end
-        new(prettyurls, disable_git, edit_branch, canonical, assets, analytics,
+        # Handle edit_branch deprecation
+        if !isa(edit_branch, Default)
+            isa(edit_link, Default) || error("Can't specify edit_branch (deprecated) and edit_link simultaneously")
+            @warn """
+            The edit_branch keyword is deprecated -- use edit_link instead.
+            Note: `edit_branch = nothing` must be changed to `edit_link = :commit`.
+            """
+            edit_link = (edit_branch === nothing) ? :commit : edit_branch
+        end
+        if isa(edit_link, Symbol) && (edit_link !== :commit)
+            throw(ArgumentError("Invalid symbol (:$edit_link) passed to edit_link."))
+        end
+        isa(edit_link, Default) && (edit_link = edit_link[])
+        new(prettyurls, disable_git, edit_link, canonical, assets, analytics,
             collapselevel, sidebar_sitename, highlights, mathengine)
     end
 end
@@ -963,7 +982,7 @@ function render_navbar(ctx, navnode, edit_page_link::Bool)
     navbar_right = div[".docs-right"]
 
     # Set the logo and name for the "Edit on.." button.
-    if edit_page_link && !ctx.settings.disable_git
+    if edit_page_link && (ctx.settings.edit_link !== nothing) && !ctx.settings.disable_git
         host_type = Utilities.repo_host_from_url(ctx.doc.user.repo)
         if host_type == Utilities.RepoGitlab
             host = "GitLab"
@@ -981,17 +1000,18 @@ function render_navbar(ctx, navnode, edit_page_link::Bool)
         hoststring = isempty(host) ? " source" : " on $(host)"
 
         pageurl = get(getpage(ctx, navnode).globals.meta, :EditURL, getpage(ctx, navnode).source)
+        edit_branch = isa(ctx.settings.edit_link, String) ? ctx.settings.edit_link : nothing
         url = if Utilities.isabsurl(pageurl)
             pageurl
         else
             if !(pageurl == getpage(ctx, navnode).source)
                 # need to set users path relative the page itself
                 pageurl = joinpath(first(splitdir(getpage(ctx, navnode).source)), pageurl)
             end
-            Utilities.url(ctx.doc.user.repo, pageurl, commit=ctx.settings.edit_branch)
+            Utilities.url(ctx.doc.user.repo, pageurl, commit=edit_branch)
         end
         if url !== nothing
-            edit_verb = (ctx.settings.edit_branch === nothing) ? "View" : "Edit"
+            edit_verb = (edit_branch === nothing) ? "View" : "Edit"
             title = "$(edit_verb)$hoststring"
             push!(navbar_right.nodes,
                 a[".docs-edit-link", :href => url, :title => title](