Merge pull request #1866 from JuliaDocs/mp/0.27.20

Backports for 0.27.20
JuliaDocs · Jul 10, 2022 · 7a77b21 · 7a77b21 · mortenpi · Jul 10, 2022
2 parents f2694ee + df1bdcc
commit 7a77b21
Show file tree

Hide file tree

Showing 19 changed files with 595 additions and 150 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,20 @@
 # Documenter.jl changelog
 
+## Version `v0.27.20`
+
+* ![Enhancement][badge-enhancement] The various JS and font dependencies of the HTML backend have been updated to the latest non-breaking versions. ([#1844][github-1844], [#1846][github-1846])
+
+  - MathJax 3 has been updated from `v3.2.0` to `v3.2.2`.
+  - JuliaMono has been updated from `v0.044` to `v0.045`.
+  - Font Awesome has been updated from `v5.15.3` to `v5.15.4`.
+  - highlight.js has been updated from `v11.0.1` to `v11.5.1`.
+  - KaTeX has been updated from `v0.13.11` to `v0.13.24`.
+
+* ![Experimental][badge-experimental] `deploydocs` now supports "deploying to tarball" (rather than pushing to the `gh-pages` branch) via the undocumented experiments `archive` keyword. ([#1865][github-1865])
+* ![Bugfix][badge-bugfix] When including docstrings for an alias, Documenter now correctly tries to include the exactly matching docstring first, before checking for signature subtypes. ([#1842][github-1842])
+* ![Bugfix][badge-bugfix] When checking for missing docstrings, Documenter now correctly handles docstrings for methods that extend bindings from other modules that have not been imported into the current module. ([#1695][github-1695], [#1857][github-1857], [#1861][github-1861])
+* ![Bugfix][badge-bugfix] By overriding `GIT_TEMPLATE_DIR`, `git` no longer picks up arbitrary user templates and hooks when internally called by Documenter. ([#1862][github-1862])
+
 ## Version `v0.27.19`
 
 * ![Enhancement][badge-enhancement] Documenter can now build draft version of HTML documentation by passing `draft=true` to `makedocs`. Draft mode skips potentially expensive parts of the building process and can be useful to get faster feedback when writing documentation. Draft mode currently skips doctests, `@example`-, `@repl`-, `@eval`-, and `@setup`-blocks. Draft mode can be disabled (or enabled) on a per-page basis by setting `Draft = true` in an `@meta` block. ([#1836][github-1836])
@@ -999,6 +1014,7 @@
 [github-1689]: https://github.com/JuliaDocs/Documenter.jl/pull/1689
 [github-1691]: https://github.com/JuliaDocs/Documenter.jl/pull/1691
 [github-1693]: https://github.com/JuliaDocs/Documenter.jl/issues/1693
+[github-1695]: https://github.com/JuliaDocs/Documenter.jl/issues/1695
 [github-1696]: https://github.com/JuliaDocs/Documenter.jl/pull/1696
 [github-1698]: https://github.com/JuliaDocs/Documenter.jl/issues/1698
 [github-1699]: https://github.com/JuliaDocs/Documenter.jl/pull/1699
@@ -1051,6 +1067,13 @@
 [github-1834]: https://github.com/JuliaDocs/Documenter.jl/pull/1834
 [github-1836]: https://github.com/JuliaDocs/Documenter.jl/pull/1836
 [github-1838]: https://github.com/JuliaDocs/Documenter.jl/pull/1838
+[github-1842]: https://github.com/JuliaDocs/Documenter.jl/pull/1842
+[github-1844]: https://github.com/JuliaDocs/Documenter.jl/pull/1844
+[github-1846]: https://github.com/JuliaDocs/Documenter.jl/pull/1846
+[github-1857]: https://github.com/JuliaDocs/Documenter.jl/issues/1857
+[github-1861]: https://github.com/JuliaDocs/Documenter.jl/pull/1861
+[github-1862]: https://github.com/JuliaDocs/Documenter.jl/pull/1862
+[github-1865]: https://github.com/JuliaDocs/Documenter.jl/pull/1865
 <!-- end of issue link definitions -->
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079

diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "Documenter"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.27.19"
+version = "0.27.20"
 
 [deps]
 ANSIColoredPrinters = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"

diff --git a/docs/src/man/examples.md b/docs/src/man/examples.md
@@ -48,7 +48,7 @@ Packages that have tagged versions available in the general Registry:
 - [PhyloNetworks.jl](https://crsl4.github.io/PhyloNetworks.jl/stable/)
 - [PrivateModules.jl](https://michaelhatherly.github.io/PrivateModules.jl/stable/)
 - [Query.jl](https://www.queryverse.org/Query.jl/stable/)
-- [SimGBS.jl](https://kanji709.github.io/SimGBS.jl/dev/)
+- [SimGBS.jl](https://anshess.github.io/SimGBS.jl/stable/)
 - [TaylorSeries.jl](https://juliadiff.org/TaylorSeries.jl/stable/)
 - [Weave.jl](https://weavejl.mpastell.com/stable/)
 

diff --git a/src/DocChecks.jl b/src/DocChecks.jl
@@ -60,9 +60,11 @@ function missingdocs(doc::Documents.Document)
                 println(b, "    $binding", sig ≡ Union{} ? "" : " :: $sig")
             end
         end
-        println(b, """\n
-            These are docstrings in the checked modules (configured with the modules keyword)
-            that are not included in @docs or @autodocs blocks.""")
+        println(b)
+        print(b, """
+        These are docstrings in the checked modules (configured with the modules keyword)
+        that are not included in @docs or @autodocs blocks.
+        """)
         @docerror(doc, :missing_docs, String(take!(b)))
     end
 end
@@ -76,12 +78,19 @@ function allbindings(checkdocs::Symbol, mods)
 end
 
 function allbindings(checkdocs::Symbol, mod::Module, out = Dict{Utilities.Binding, Set{Type}}())
-    for (obj, doc) in meta(mod)
-        isa(obj, IdDict{Any,Any}) && continue
-        name = nameof(obj)
-        isexported = Base.isexported(mod, name)
+    for (binding, doc) in meta(mod)
+        # The keys of the docs meta dictonary should always be Docs.Binding objects in
+        # practice. However, the key type is Any, so it is theoretically possible that
+        # some non-binding metadata gets added to the dict. So on the off-chance that has
+        # happened, we simply ignore those entries.
+        isa(binding, Docs.Binding) || continue
+        # We only consider a name exported only if it actually exists in the module, either
+        # by virtue of being defined there, or if it has been brought into the scope with
+        # import/using.
+        name = nameof(binding)
+        isexported = (binding == Utilities.Binding(mod, name)) && Base.isexported(mod, name)
         if checkdocs === :all || (isexported && checkdocs === :exports)
-            out[Utilities.Binding(mod, name)] = Set(sigs(doc))
+            out[binding] = Set(sigs(doc))
         end
     end
     out

diff --git a/src/DocSystem.jl b/src/DocSystem.jl
@@ -162,23 +162,19 @@ const CACHED = IdDict{Any,Any}()
 """
 $(SIGNATURES)
 
-Find all `DocStr` objects that match the provided arguments:
-
+Find all `DocStr` objects that match the provided arguments exactly.
 - `binding`: the name of the object.
 - `typesig`: the signature of the object. Default: `Union{}`.
-- `compare`: how to compare signatures? Exact (`==`) or subtypes (`<:`). Default: `<:`.
+- `compare`: how to compare signatures? (`==` (default), `<:` or `>:`)
 - `modules`: which modules to search through. Default: *all modules*.
-- `aliases`: check aliases of `binding` when nothing is found. Default: `true`.
 
-Returns a `Vector{DocStr}` ordered by definition order in `0.5` and by
-`type_morespecific` in `0.4`.
+Return a `Vector{DocStr}` ordered by definition order.
 """
-function getdocs(
+function getspecificdocs(
         binding::Docs.Binding,
-        typesig::Type = Union{};
+        typesig::Type = Union{},
         compare = (==),
         modules = Docs.modules,
-        aliases = true,
     )
     # Fall back to searching all modules if user provides no modules.
     modules = isempty(modules) ? Docs.modules : modules
@@ -200,28 +196,44 @@ function getdocs(
             end
         end
     end
-    if compare == (==)
-        # Exact matching of signatures:
-        #
-        # When we get a single match from using `==` as the comparision then we just return
-        # that one result.
-        #
-        # Otherwise we fallback to comparing signatures using `<:` to match, hopefully, a
-        # wider range of possible docstrings.
-        if length(results) == 1
-            results
-        else
-            getdocs(binding, typesig; compare = (<:), modules = modules, aliases = aliases)
-        end
-    else
-        # When nothing is found we check whether the `binding` is an alias of some other
-        # `Binding`. If so then we redo the search using that `Binding` instead.
-        if aliases && isempty(results) && (b = aliasof(binding)) != binding
-            getdocs(b, typesig; compare = compare, modules = modules)
-        else
-            results
+    results
+end
+
+"""
+$(SIGNATURES)
+
+Find all `DocStr` objects that somehow match the provided arguments.
+That is, if [`getspecificdocs`](@ref) fails, get docs for aliases of
+`binding` (unless `aliases` is set to `false). For `compare` being `==` also
+try getting docs for `<:`.
+"""
+function getdocs(
+        binding::Docs.Binding,
+        typesig::Type = Union{};
+        compare = (==),
+        modules = Docs.modules,
+        aliases = true,
+    )
+    # First, we try to find the docs that _exactly_ match the binding. If you
+    # have aliases, you can have a separate docstring attached to the alias.
+    results = getspecificdocs(binding, typesig, compare, modules)
+    # If we don't find anything, we'll loosen the function signature comparison
+    # to allow for subtypes, to find any signatures that would get called in
+    # dispatch for this method (i.e. supertype signatures).
+    if isempty(results) && compare == (==)
+        results = getspecificdocs(binding, typesig, (<:), modules)
+    end
+    # If we still can't find anything, `aliases` is set, and this binding is
+    # indeed an alias, we'll fetch the docstrings for the original object, first
+    # as an exact match (if relevant) and then also falling back to a subtype
+    # search.
+    if isempty(results) && aliases && (b = aliasof(binding)) != binding
+        results = getspecificdocs(b, typesig, compare, modules)
+        if isempty(results) && compare == (==)
+            results = getspecificdocs(b, typesig, (<:), modules)
         end
     end
+    results
 end
 
 """

diff --git a/src/Documenter.jl b/src/Documenter.jl
@@ -62,7 +62,7 @@ include("DocChecks.jl")
 include("Writers/Writers.jl")
 include("Deps.jl")
 
-import .Utilities: Selectors
+import .Utilities: Selectors, git
 import .Writers.HTMLWriter: HTML, asset
 import .Writers.HTMLWriter.RD: KaTeX, MathJax, MathJax2, MathJax3
 import .Writers.LaTeXWriter: LaTeX
@@ -534,13 +534,22 @@ function deploydocs(;
         forcepush::Bool = false,
         deploy_config = auto_detect_deploy_system(),
         push_preview::Bool = false,
+
+        archive = nothing, # experimental and undocumented
     )
 
     # Try to figure out default branch (see #1443 and #1727)
     if devbranch === nothing
         devbranch = Utilities.git_remote_head_branch("deploydocs(devbranch = ...)", root)
     end
 
+    if archive !== nothing
+        # If archive is a relative path, we'll make it relative to the make.jl
+        # directory (e.g. docs/)
+        archive = joinpath(root, archive)
+        ispath(archive) && error("Output archive exists: $archive")
+    end
+
     deploy_decision = deploy_folder(deploy_config;
                                     branch=branch,
                                     branch_previews=branch_previews,
@@ -574,7 +583,7 @@ function deploydocs(;
             # the working directory has been changed (e.g. if the makedocs' build argument is
             # outside root).
             sha = try
-                readchomp(`git rev-parse --short HEAD`)
+                readchomp(`$(git()) rev-parse --short HEAD`)
             catch
                 # git rev-parse will throw an error and return code 128 if it is not being
                 # run in a git repository, which will make run/readchomp throw an exception.
@@ -597,7 +606,7 @@ function deploydocs(;
                     branch=deploy_branch, dirname=dirname, target=target,
                     sha=sha, deploy_config=deploy_config, subfolder=deploy_subfolder,
                     devurl=devurl, versions=versions, forcepush=forcepush,
-                    is_preview=deploy_is_preview,
+                    is_preview=deploy_is_preview, archive=archive,
                 )
             end
         end
@@ -618,7 +627,7 @@ function git_push(
         root, temp, repo;
         branch="gh-pages", dirname="", target="site", sha="", devurl="dev",
         versions, forcepush=false, deploy_config, subfolder,
-        is_preview::Bool = false,
+        is_preview::Bool = false, archive,
     )
     dirname = isempty(dirname) ? temp : joinpath(temp, dirname)
     isdir(dirname) || mkpath(dirname)
@@ -628,17 +637,17 @@ function git_push(
     # Generate a closure with common commands for ssh and https
     function git_commands(sshconfig=nothing)
         # Setup git.
-        run(`git init`)
-        run(`git config user.name "Documenter.jl"`)
-        run(`git config user.email "documenter@juliadocs.github.io"`)
+        run(`$(git()) init`)
+        run(`$(git()) config user.name "Documenter.jl"`)
+        run(`$(git()) config user.email "documenter@juliadocs.github.io"`)
         if sshconfig !== nothing
-            run(`git config core.sshCommand "ssh -F $(sshconfig)"`)
+            run(`$(git()) config core.sshCommand "ssh -F $(sshconfig)"`)
         end
 
         # Fetch from remote and checkout the branch.
-        run(`git remote add upstream $upstream`)
+        run(`$(git()) remote add upstream $upstream`)
         try
-            run(`git fetch upstream`)
+            run(`$(git()) fetch upstream`)
         catch e
             @error """
             Git failed to fetch $upstream
@@ -650,7 +659,7 @@ function git_push(
         end
 
         try
-            run(`git checkout -b $branch upstream/$branch`)
+            run(`$(git()) checkout -b $branch upstream/$branch`)
         catch e
             @info """
             Checking out $branch failed, creating a new orphaned branch.
@@ -659,8 +668,8 @@ function git_push(
             from Git in this situation.
             """
             @debug "checking out $branch failed with error: $e"
-            run(`git checkout --orphan $branch`)
-            run(`git commit --allow-empty -m "Initial empty commit for docs"`)
+            run(`$(git()) checkout --orphan $branch`)
+            run(`$(git()) commit --allow-empty -m "Initial empty commit for docs"`)
         end
 
         # Copy docs to `subfolder` directory.
@@ -701,14 +710,18 @@ function git_push(
         end
 
         # Add, commit, and push the docs to the remote.
-        run(`git add -A .`)
-        if !success(`git diff --cached --exit-code`)
-            if forcepush
-                run(`git commit --amend --date=now -m "build based on $sha"`)
-                run(`git push -fq upstream HEAD:$branch`)
+        run(`$(git()) add -A .`)
+        if !success(`$(git()) diff --cached --exit-code`)
+            if archive !== nothing
+                run(`$(git()) commit -m "build based on $sha"`)
+                @info "Skipping push and writing repository to an archive" archive
+                run(`$(git()) archive -o $(archive) HEAD`)
+            elseif forcepush
+                run(`$(git()) commit --amend --date=now -m "build based on $sha"`)
+                run(`$(git()) push -fq upstream HEAD:$branch`)
             else
-                run(`git commit -m "build based on $sha"`)
-                run(`git push -q upstream HEAD:$branch`)
+                run(`$(git()) commit -m "build based on $sha"`)
+                run(`$(git()) push -q upstream HEAD:$branch`)
             end
         else
             @debug "new docs identical to the old -- not committing nor pushing."
@@ -830,7 +843,7 @@ function gitrm_copy(src, dst)
     if isdir(dst)
         for x in filter!(!in((".git", "previews")), readdir(dst))
             # --ignore-unmatch so that we wouldn't get errors if dst does not exist
-            run(`git rm -rf --ignore-unmatch $(joinpath(dst, x))`)
+            run(`$(git()) rm -rf --ignore-unmatch $(joinpath(dst, x))`)
         end
     end
     # git rm also remove parent directories