Refactor the repo/remote handling

CHANGELOG.md

@@ -8,6 +8,14 @@
   **For upgrading:** To keep using the Markdown backend, refer to the [DocumenterMarkdown package][documentermarkdown]. That package might not immediately support the latest Documenter version, however.
 
 * ![Enhancement][badge-enhancement] The `ansicolor` keyword to `HTML()` now defaults to true, meaning that executed outputs from `@example`- and `@repl`-blocks are now by default colored (if they emit colored output). ([#1828][github-1828])
+* ![Enhancement][badge-enhancement] A more general API is now available to configure the remote repository URLs via the `repo` argument of `makedocs` by passing objects that are subtypes of `Remotes.Remote` and implement its interface (e.g. `Remotes.GitHub`). ([#1808][github-1808])
+* ![Enhancement][badge-enhancement] Broken issue references (i.e. links like `[#1234](@ref)`, but when Documenter is unable to determine the remote GitHub repository) now generate `:cross_references` errors that can be caught via the `strict` keyword. ([#1808][github-1808])
+
+  This is **potentially breaking** as it can cause previously working builds to fail if they are being run in strict mode. However, such builds were already leaving broken links in the generated documentation.
+
+  **For upgrading:** the easiest way to fix the build is to remove the offending `@ref` links. Alternatively, the `repo` argument to `makedocs` can be set to the appropriate `Remotes.Remote` object that implements the `Remotes.issueurl` function, which would make sure that correct URLs are generated.
+
+* ![Bugfix][badge-bugfix] Documenter now generates the correct source URLs for docstrings from other packages when the `repo` argument to `makedocs` is set (note: the source links to such docstrings only work if the external package is cloned from GitHub and added as a dev-dependency). However, this change **breaks** the case where the `repo` argument is used to override the main package/repository URL, assuming the repository is cloned from GitHub. ([#1808][github-1808])
 
 ## Version `v0.27.21`
 
@@ -1067,6 +1075,7 @@
 [github-1805]: https://github.com/JuliaDocs/Documenter.jl/pull/1805
 [github-1806]: https://github.com/JuliaDocs/Documenter.jl/pull/1806
 [github-1807]: https://github.com/JuliaDocs/Documenter.jl/pull/1807
+[github-1808]: https://github.com/JuliaDocs/Documenter.jl/pull/1808
 [github-1810]: https://github.com/JuliaDocs/Documenter.jl/issues/1810
 [github-1811]: https://github.com/JuliaDocs/Documenter.jl/pull/1811
 [github-1814]: https://github.com/JuliaDocs/Documenter.jl/issues/1814

docs/src/lib/internals/utilities.md

@@ -3,3 +3,8 @@
 ```@autodocs
 Modules = [Documenter.Utilities]
 ```
+
+```@docs
+Remotes.URL
+Remotes.repofile
+```

docs/src/lib/public.md

@@ -31,6 +31,23 @@ DocMeta.getdocmeta
 DocMeta.setdocmeta!
 ```
 
+### Remotes
+
+```@docs
+Documenter.Remotes
+Documenter.Remotes.GitHub
+```
+
+The following types and functions and relevant when creating custom
+[`Remote`](@ref Documenter.Remotes.Remote) types:
+
+```@docs
+Documenter.Remotes.Remote
+Documenter.Remotes.repourl
+Documenter.Remotes.fileurl
+Documenter.Remotes.issueurl
+```
+
 ## DocumenterTools
 
 ```@docs

src/CrossReferences.jl

@@ -13,6 +13,7 @@ import ..Documenter:
     Utilities.@docerror
 
 using DocStringExtensions
+using .Utilities: Remotes
 import Markdown
 
 """
@@ -213,8 +214,13 @@ getsig(λ::Union{Function, DataType}, typesig) = Base.tuple_type_tail(which(λ,
 # -----------------------------
 
 function issue_xref(link::Markdown.Link, num, meta, page, doc)
-    link.url = isempty(doc.internal.remote) ? link.url :
-        "https://github.com/$(doc.internal.remote)/issues/$num"
+    # Update issue links starting with a hash, but only if our Remote supports it
+    issue_url = Remotes.issueurl(doc.user.remote, num)
+    if isnothing(issue_url)
+        @docerror(doc, :cross_references, "unable to generate issue reference for '[`#$num`](@ref)' in $(Utilities.locrepr(page.source)).")
+    else
+        link.url = issue_url
+    end
 end
 
 end

src/Documenter.jl

@@ -61,14 +61,14 @@ include("CrossReferences.jl")
 include("DocChecks.jl")
 include("Writers/Writers.jl")
 
-import .Utilities: Selectors, git
+import .Utilities: Selectors, Remotes, git
 import .Writers.HTMLWriter: HTML, asset
 import .Writers.HTMLWriter.RD: KaTeX, MathJax, MathJax2, MathJax3
 import .Writers.LaTeXWriter: LaTeX
 
 # User Interface.
 # ---------------
-export makedocs, deploydocs, hide, doctest, DocMeta, asset,
+export makedocs, deploydocs, hide, doctest, DocMeta, asset, Remotes,
     KaTeX, MathJax, MathJax2, MathJax3
 
 """
@@ -158,23 +158,16 @@ makedocs(
 and so any docstring from the module `Documenter` that is not spliced into the generated
 documentation in `build` will raise a warning.
 
-**`repo`** specifies a template for the "link to source" feature. If you are
-using GitHub, this is automatically generated from the remote. If you are using
-a different host, you can use this option to tell Documenter how URLs should be
-generated. The following placeholders will be replaced with the respective
-value of the generated link:
+**`repo`** specifies the browsable remote repository (e.g. on github.com). This is used for
+generating various remote links, such as the "source" links on docstrings. It can either
+be passed an object that implements the [`Remotes.Remote`](@ref) interface (e.g.
+[`Remotes.GitHub`](@ref)) or a template string. If a string is passed, it is interpreted
+according to the rules described in [`Remotes.URL`](@ref).
 
-  - `{commit}` Git branch or tag name, or commit hash
-  - `{path}` Path to the file in the repository
-  - `{line}` Line (or range of lines) in the source file
-
-BitBucket, GitLab and Azure DevOps are supported along with GitHub, for example:
-
-```julia
-makedocs(repo = \"https://gitlab.com/user/project/blob/{commit}{path}#{line}\") # GitLab
-makedocs(repo = \"https://dev.azure.com/org/project/_git/repo?path={path}&version={commit}{line}&lineStartColumn=1&lineEndColumn=1\") # Azure DevOps
-makedocs(repo = \"https://bitbucket.org/user/project/src/{commit}/{path}#lines-{line}\") # BitBucket
-```
+By default, the repository is assumed to be hosted on GitHub, and the remote URL is
+determined by first checking the URL of the `origin` Git remote, and then falling back to
+checking the `TRAVIS_REPO_SLUG` (for Travis CI) and `GITHUB_REPOSITORY` (for GitHub Actions)
+environment variables. If this automatic procedure fails, a warning is printed.
 
 **`highlightsig`** enables or disables automatic syntax highlighting of leading, unlabeled
 code blocks in docstrings (as Julia code). For example, if your docstring begins with an

src/Documents.jl

@@ -16,7 +16,7 @@ import ..Documenter:
     Plugin,
     Writer
 
-import ..Documenter.Utilities.Markdown2
+using ..Documenter.Utilities: Remotes, Markdown2
 using DocStringExtensions
 import Markdown
 using Unicode
@@ -244,7 +244,7 @@ struct User
     strict::Union{Bool,Symbol,Vector{Symbol}} # Throw an exception when any warnings are encountered.
     pages   :: Vector{Any}    # Ordering of document pages specified by the user.
     expandfirst::Vector{String} # List of pages that get "expanded" before others
-    repo    :: String  # Template for URL to source code repo
+    remote  :: Union{Remotes.Remote,Nothing} # Remote Git repository information
     sitename:: String
     authors :: String
     version :: String # version string used in the version selector by default
@@ -257,7 +257,6 @@ Private state used to control the generation process.
 """
 struct Internal
     assets  :: String             # Path where asset files will be copied to.
-    remote  :: String             # The remote repo on github where this package is hosted.
     navtree :: Vector{NavNode}           # A vector of top-level navigation items.
     navlist :: Vector{NavNode}           # An ordered list of `NavNode`s that point to actual pages
     headers :: Anchors.AnchorMap         # See `modules/Anchors.jl`. Tracks `Markdown.Header` objects.
@@ -300,7 +299,7 @@ function Document(plugins = nothing;
         modules  :: Utilities.ModVec = Module[],
         pages    :: Vector           = Any[],
         expandfirst :: Vector        = String[],
-        repo     :: AbstractString   = "",
+        repo     :: Union{Remotes.Remote, AbstractString} = "",
         sitename :: AbstractString   = "",
         authors  :: AbstractString   = "",
         version :: AbstractString    = "",
@@ -320,6 +319,20 @@ function Document(plugins = nothing;
         version = "git:$(Utilities.get_commit_short(root))"
     end
 
+    remote = if isa(repo, AbstractString) && isempty(repo)
+        # If the user does not provide the `repo` argument, we'll try to automatically
+        # detect the remote repository by looking at the Git repository remote. This only
+        # works if the repository is hosted on GitHub. If that fails, it falls back to
+        # TRAVIS_REPO_SLUG.
+        Utilities.getremote(root)
+    elseif repo isa AbstractString
+        # Use the old template string parsing logic if a string was passed.
+        Remotes.URL(repo)
+    else
+        # Otherwise it should be some Remote object
+        repo
+    end
+
     user = User(
         root,
         source,
@@ -336,7 +349,7 @@ function Document(plugins = nothing;
         strict,
         pages,
         expandfirst,
-        repo,
+        remote,
         sitename,
         authors,
         version,
@@ -345,7 +358,6 @@ function Document(plugins = nothing;
     )
     internal = Internal(
         Utilities.assetsdir(),
-        Utilities.getremote(root),
         [],
         [],
         Anchors.AnchorMap(),