Add alias_methods_as_function=true

This adds the keyword argument `alias_methods_as_function` to
`InterLinks` (`true` by default) which adds `function` aliases for
`method` items in any inventory that is loaded. An alias is only created
if it is unambiguous, i.e., if there is only a single documented method
for a function and no existing docstring for the function.

The feature is to work around Documenter's `@autodocs` inserting method
docstring instead of function docstrings and the fact that method
docstrings can be exceedingly verbose to reference in an `@extref`. With
the alias, an `@extref` can be, e.g.,

     [`Documenter.Selectors.dispatch`](@extref)

instead of the verbose

    [`Documenter.Selectors.dispatch`](@extref `Documenter.Selectors.dispatch-Union{Tuple{T}, Tuple{Type{T}, Vararg{Any}}} where T<:Documenter.Selectors.AbstractSelector`)

that would be necessary without `alias_method_as_function=false`.

Author: goerz

docs/src/howtos.md

@@ -135,7 +135,7 @@ Essentially, what we've done here is to open a Julia REPL like we normally would
 The above routine is how the local [inventory files](https://github.com/JuliaDocs/DocumenterInterLinks.jl/tree/master/docs/src/inventories) used in this documentation were generated. Using the TOML format is recommended for any inventory that will be committed to Git, as it is both human-readable and easier for `git` to track.
 
 !!! warning
-    Make sure that `prettyurls=true` in [`Documenter.makedocs`](@ref), or, more specifically, that the `prettyurls` option is not set conditionally with something like `prettyurls = get(ENV, "CI", nothing) == "true"`. This would cause a mismatch between the locally generated inventory and the deployed documentation.
+    Make sure that `prettyurls=true` in [`Documenter.makedocs`](@extref), or, more specifically, that the `prettyurls` option is not set conditionally with something like `prettyurls = get(ENV, "CI", nothing) == "true"`. This would cause a mismatch between the locally generated inventory and the deployed documentation.
 
 
 Some local inventory files are also available in the [project wiki](https://github.com/JuliaDocs/DocumenterInterLinks.jl/wiki/Inventory-File-Repository). You may contribute your own generated inventories there.

docs/src/syntax.md

@@ -55,7 +55,7 @@ where the latter two are unnecessarily verbose, as `Documenter.makedocs` is alre
 
 The short-circuit mechanism only works if the project name used in the instantiation of [`InterLinks`](@ref) matches the package name as it occurs in the fully specified name of any code object. That is, name the project `"Documenter"`, not, e.g., `"Documenter121"` for version `1.2.1` of `Documenter`.
 
-When this is not possible, e.g. for the `Julia` project which contains many different modules without a common prefix (`Base`, `Core`, `LinearAlgebra`, …), it is best to declare that project as the *first* element in [`InterLinks`](@ref). That way,
+When this is not possible, e.g., for the `Julia` project which contains many different modules without a common prefix (`Base`, `Core`, `LinearAlgebra`, …), it is best to declare that project as the *first* element in [`InterLinks`](@ref). That way,
 
 ```
 [`Base.sort!`](@extref)
@@ -78,11 +78,11 @@ looks in the `Julia` project first, avoiding the need for
 
 With the [Performance Tips](@ref) in mind, not all of the [10 possible Syntax forms](@ref Syntax) are recommended in practice. For maximum clarity and performance, use the following guidelines:
 
-1. When referencing section headers in another project, e.g. the [Basic Markdown](@extref Documenter Basic-Markdown) section in Documenter's documentation, look up the appropriate sluggified name:
+1. When referencing section headers in another project, e.g., the [Basic Markdown](@extref Documenter Basic-Markdown) section in Documenter's documentation, look up the appropriate sluggified name:
 
    ```@example syntax
    using DocumenterInterLinks # hide
-   links = InterLinks("Documenter" => ("https://documenter.juliadocs.org/stable/", joinpath(@__DIR__, "inventories", "Documenter.toml")),) # hide
+   links = InterLinks("Documenter" => ("https://documenter.juliadocs.org/stable/", joinpath(@__DIR__, "inventories", "Documenter.toml")),"Julia" => ("https://docs.julialang.org/en/v1/", joinpath(@__DIR__, "inventories", "Julia.toml")),) # hide
    links["Documenter"]("Basic Markdown")
    ```
 
@@ -100,27 +100,27 @@ With the [Performance Tips](@ref) in mind, not all of the [10 possible Syntax fo
 
    Make sure that `Documenter` is a project name in `links` (see [Performance Tips](@ref)).
 
-   This gets slightly more complicated when the code object is a "method" (where the docstring is for specific types of arguments), e.g., [`Documenter.parseblock`](@extref `Documenter.parseblock-Tuple{AbstractString, Any, Any}`). You will generally have to look up the full name
+   This gets slightly more complicated when the code object is a "method" (where the docstring is for specific types of arguments), e.g., [`Base.Filesystem.cd`](@extref `Base.Filesystem.cd-Tuple{AbstractString}`). You will generally have to look up the full name
 
    ```@example syntax
-   links["Documenter"]("parseblock")
+   links["Julia"]("Base.Filesystem.cd")
    ```
 
    and then use form (3),
 
    ```
-   [`Documenter.parseblock`](@extref `Documenter.parseblock-Tuple{AbstractString, Any, Any}`)
+   [`Base.Filesystem.cd`](@extref `Base.Filesystem.cd-Tuple{AbstractString}`)
    ```
 
-   The use of backticks around the full method name is optional, but recommended when there are spaces in the name.
+   to link to a specific method. The use of backticks around the full method name is optional, but recommended especially when there are spaces in the type description. Note that if there is only a single method for a function, [`InterLinks`](@ref) by default (due to `alias_methods_as_function`) will add an alias that links the function name to that method docstring, allowing to use the shorter function name as a convenient target for the reference.
 
    If the module name of the object cannot match the project name (e.g., for the `Julia` documentation, which contains docstrings for `Base`, `Core`, `LinearAlgebra`, etc.), use form (5),
 
    ```
    [`Base.sort!`](@extref Julia)
    ```
 
-3. When referencing a page, e.g. the [Home page of the Documenter documentation](@extref Documenter :doc:`index`), use form (9):
+3. When referencing a page, e.g., the [Home page of the Documenter documentation](@extref Documenter :doc:`index`), use form (9):
 
    ```
    [Home page of the Documenter documentation](@extref Documenter :doc:`index`)

docs/src/write_inventory.md

@@ -20,7 +20,7 @@ For a Documenter-based project, the automatic inventory contains:
 !!! info
     You  probably will not need to worry about the information in this section.
 
-The inventory for a `Documenter`-based documentation includes [entries](@extref `DocInventories.InventoryItem`) for docstrings using an [ad-hoc](@ref Compatibility-with-Sphinx) `jl` domain. The `role` for each entry matches how `Documenter` identifies the underlying object with [`Documenter.doccat`](@extref `Documenter.doccat-Tuple{Documenter.Object}`). You will find this identification as part of how the docstring shows in the documentation; for example, note the "— Type" in the header of [` DocumenterInterLinks.InterLinks`](@ref). The `role` that will be written to the inventory is simply the lowercase string of this identification. Currently, `Documenter` uses the following:
+The inventory for a `Documenter`-based documentation includes [entries](@extref `DocInventories.InventoryItem`) for docstrings using an [ad-hoc](@ref Compatibility-with-Sphinx) `jl` domain. The `role` for each entry matches how `Documenter` identifies the underlying object with [`Documenter.doccat`](@extref). You will find this identification as part of how the docstring shows in the documentation; for example, note the "— Type" in the header of [` DocumenterInterLinks.InterLinks`](@ref). The `role` that will be written to the inventory is simply the lowercase string of this identification. Currently, `Documenter` uses the following:
 
 * "Macro" (role `macro`): for macros. For example, ```":jl:macro:`Base.@inbounds`"``` for [`Base.@inbounds`](@extref Julia :jl:macro:`Base.@inbounds`).
 * "Keyword" (role `keyword`): for Julia keywords (used in the documentation of the Julia language itself, only). For example, ```":jl:keyword:`if`"``` for [the `if` keyword](@extref Julia :jl:keyword:`if`).

src/interlinks.jl

@@ -1,5 +1,5 @@
 using Documenter: Plugin
-using DocInventories: Inventory, uri, spec, split_url
+using DocInventories: Inventory, InventoryItem, uri, spec, split_url, search_in_inventory
 
 
 """
@@ -13,7 +13,8 @@ links = InterLinks(
         "https://project3.url/",
         joinpath(@__DIR__, "src", "interlinks", "inventory.file")
     );
-    default_inventory_file="objects.inv"
+    default_inventory_file="objects.inv",
+    alias_methods_as_function=true,
 )
 ```
 
@@ -76,6 +77,29 @@ any of the following forms:
 
 * A [`DocInventories.Inventory`](@extref) instance.
 
+# Keyword arguments
+
+* `default_inventory_file`: The file name for the inventory file to use if the
+  "inventory location" is given as the root URL. Since both Sphinx and
+  Documenter automatically write `objects.inv`, there is little conceivable
+  reason to set this to something other than the default `objects.inv`.
+* `alias_methods_as_function`: If `true` (default), for any inventory loaded
+  from a file or URL, automatically add a `:jl:function:` alias for any
+  `:jl:method` if that alias is unambiguous. This accounts for Documenter
+  preferentially generating method-docstrings from `@autodoc` blocks, even if
+  that method is the only method for the underlying function. For example, the
+  [`Documenter.Selectors.dispatch`](@extref) function only has a
+  method-docstring that would have to be referenced as the excessively long
+
+  ```
+  [`Documenter.Selectors.dispatch`](@extref `Documenter.Selectors.dispatch-Union{Tuple{T}, Tuple{Type{T}, Vararg{Any}}} where T<:Documenter.Selectors.AbstractSelector`)
+  ```
+
+  With the alias, this can be shortened to
+  ```[`Documenter.Selectors.dispatch`](@extref)```. No alias will be created
+  if there are docstrings for multiple methods of the same function, or if
+  there is an existing function docstring.
+
 # Properties
 
 * `names`: A list of project names
@@ -175,7 +199,11 @@ end
 
 
 
-function InterLinks(mapping...; default_inventory_file="objects.inv")
+function InterLinks(
+    mapping...;
+    default_inventory_file="objects.inv",
+    alias_methods_as_function=true
+)
     names = String[]
     inventories_list = Inventory[]
     try
@@ -204,6 +232,9 @@ function InterLinks(mapping...; default_inventory_file="objects.inv")
                     try
                         inventory = Inventory(source; root_url=root_url)
                         @debug "Successfully loaded inventory $(repr(project)) from source $(repr(source))."
+                        if alias_methods_as_function
+                            _set_method_aliases!(inventory)
+                        end
                         break  # stop after first successful source
                     catch exception
                         msg = "Failed to load inventory $(repr(project)) from possible source $(repr(source))."
@@ -263,6 +294,34 @@ function (links::InterLinks)(search)
 end
 
 
+function _set_method_aliases!(inventory)
+    aliases = Dict{String,Vector{String}}()
+    for method_item in search_in_inventory(inventory, ":jl:method:`")
+        func_name = replace(method_item.name, r"-.*$" => "")
+        if haskey(aliases, func_name)
+            push!(aliases[func_name], spec(method_item))
+        else
+            aliases[func_name] = [spec(method_item)]
+        end
+    end
+    for (func_name, method_specs) in aliases
+        func_spec = ":jl:function:`$func_name`"
+        if length(method_specs) == 1
+            method_spec = method_specs[1]
+            if isnothing(inventory[func_spec])
+                @debug "Setting alias $method_spec -> $func_spec"
+                push!(inventory, InventoryItem(func_spec => uri(inventory[method_spec])))
+            else
+                @debug "Not setting alias $method_spec -> $func_spec: function entry already exists"
+            end
+        else
+            @debug "Not setting alias to $func_spec: ambiguous" method_specs
+        end
+    end
+    return inventory
+end
+
+
 """Find an `@extref` link in any of the [`InterLinks`](@ref) inventories.
 
 ```julia
@@ -273,7 +332,7 @@ finds `extref` in `links` and returns the full URL that resolves the link.
 
 # Arguments
 
-* `links`: the [`InterLinks`] instance to resolve the reference in
+* `links`: the [`InterLinks`](@ref) instance to resolve the reference in
 * `extref`: a string of the form
    `"@extref [project] [[:domain][:role]:]name"`
 """

test/test_fallback.jl

@@ -193,7 +193,8 @@ end
         "DocumenterInterLinks" => (
             "http://juliadocs.org/DocumenterInterLinks.jl/dev/",
             joinpath(splitext(@__FILE__)[1], "DocumenterInterLinks.toml")
-        ),
+        );
+        alias_methods_as_function=false,
     )
 
     push!(
@@ -225,7 +226,6 @@ end
     ) do dir, result, success, backtrace, output
 
         if DOCUMENTER_VERSION >= v"1.3.0-dev"
-            @test success
             @test contains(
                 output,
                 "Warning: ExternalFallbacks resolution of \"makedocs\" is ambiguous"

test/test_interlinks.jl

@@ -1,3 +1,4 @@
+using Logging
 using Test
 using TestingUtilities: @Test
 using DocInventories
@@ -207,3 +208,37 @@ end
           ["@extref Documenter :std:doc:`index`", "@extref Julia :std:doc:`index`",]
 
 end
+
+
+@testset "method aliases" begin
+    captured = IOCapture.capture(; passthrough=false) do
+        with_logger(ConsoleLogger(stdout, Logging.Debug)) do
+            InterLinks(
+                "Documenter" => (
+                    "https://documenter.juliadocs.org/stable/",
+                    joinpath(@__DIR__, "inventories", "Documenter.toml")
+                ),
+                "Julia" => (
+                    "https://docs.julialang.org/en/v1/",
+                    joinpath(@__DIR__, "inventories", "Julia.toml")
+                );
+                alias_methods_as_function=true,
+            )
+        end
+    end
+    @test contains(
+        captured.output,
+        "Setting alias :jl:method:`Documenter.nodocs-Tuple{Any}` -> :jl:function:`Documenter.nodocs`"
+    )
+    nodocs_items = captured.value["Documenter"]("Documenter.nodocs")
+    @test length(nodocs_items) == 2
+    @test Set([item.role for item in nodocs_items]) == Set(["function", "method"])
+    @test contains(
+        captured.output,
+        "Not setting alias to :jl:function:`Documenter.HTMLWriter.get_url`: ambiguous"
+    )
+    @test contains(
+        captured.output,
+        "Not setting alias :jl:method:`Base.first-Tuple{AbstractString, Integer}` -> :jl:function:`Base.first`: function entry already exists"
+    )
+end