Methods in <s>search</s> index results should display signature

[fingolfin]

If I go to https://nemocas.github.io/AbstractAlgebra.jl/latest/search/?q=modulus then the first four hits are all displayed identically as AbstractAlgebra.Generic.modulus (method).

I have to click on each (or carefully study the link URL) to figure out the difference, and thus ultimately find the correct method.

It would be much nicer if there was extra information about the signature of each method. E.g. instead of (method) one could write (method with signature modulus(a::AbstractAlgebra.PolyElem{T}) where {T <: ResElem}).

[fingolfin]

This also is relevant for the index generated by @index (CC @ThomasBreuer)

[ThomasBreuer]

As far as I see, the original problem has been solved, but the analogous problem for the index is still present. Perhaps we should change the title of the issue.

[fingolfin]

@ThomasBreuer just pointed out to me that the search results got much better, and this is indeed true! It now shows:

AbstractAlgebra.modulus (method, Univariate polynomial functionality)
AbstractAlgebra.modulus (method, Power series)
AbstractAlgebra.modulus (method, Generic Puiseux series)
AbstractAlgebra.modulus (method, Generic residue rings)

This descriptions seem to be derived from the page titles. This it is still not 100% perfect, though: if two methods for the same function are defined on the same page, they are still not distinguishable in the search results. See e.g. the two first results on https://docs.julialang.org/en/v1/search/?q=eps (but that example is not that bad, as the text for the two hits are adjacent, so I am a being rather nitpicky here).

If the index would show something similar to the search results, then that would be a great improvement.

[fingolfin]

The improved search results are from PR #1468. That PR just modifies Javascript, which means it's not immediate visible (to me, at least) how to do something equivalent in Julia).

Still, I had a look at how to improve this in the index. I think this required modifying the various writers, e.g. src/Writers/HTMLWriter.jl, and there the functions writing out Documents.IndexNode. There, we iterate over tuples (object, doc, page, mod, cat). Unfortunately I don't know what these things are, exactly... empirically (from printing them)

• object is a Documenter.Utilities.Object
• doc is.. the document being written? maybe?
• page is a string containing a path, like lib/functions.md
• mod is a Module object (presumably containing the object being documented?)
• cat is a symbol like :function

What I don't know is how to extract the "section title" (such as "Univariate polynomial functionality" in my example above) from this data.

For a function, though, the signature is available as object.signature. Since the vast majority of ambiguities in my experience is from docstrings for different methods of the same function, maybe just printing that would already be good enough...?

[fingolfin]

In case it helps someone who wants to work on this: Here is a hackish patch which shows the places to modify. I think at least showing the category (by printing cat) would be nice (this is also done in the search results). I'd like to show the signature for methods, too (one will have to think a bit about how the output should look). Perhaps in a format similar to what methods shows.

Perhaps multiple methods for the same function could also be grouped together somehow

Anyway, here is the patch:

diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl
index 4f52d9b6a..13774348c 100644
--- a/src/Writers/HTMLWriter.jl
+++ b/src/Writers/HTMLWriter.jl
@@ -1428,7 +1428,7 @@ function domify(ctx, navnode, index::Documents.IndexNode)
         path = joinpath(navnode_dir, path) # links in IndexNodes are relative to current page
         path = pretty_url(ctx, relhref(navnode_url, get_url(ctx, path)))
         url = string(path, "#", Utilities.slugify(object))
-        li(a[:href=>url](code("$(object.binding)")))
+        li(a[:href=>url](code("$(object.binding)")), " (", string(cat), ")") # TODO
     end
     ul(lis)
 end
diff --git a/src/Writers/LaTeXWriter.jl b/src/Writers/LaTeXWriter.jl
index 03fe3d495..14999ebf5 100644
--- a/src/Writers/LaTeXWriter.jl
+++ b/src/Writers/LaTeXWriter.jl
@@ -326,7 +326,7 @@ function latex(io::IO, index::Documents.IndexNode, page, doc)
         _print(io, "\\item \\hyperlink{")
         _print(io, id, "}{\\texttt{")
         latexesc(io, text)
-        _println(io, "}}")
+        _println(io, "}} ", cat) # FIXME: wait, this is already here?!?
     end
     _println(io, "\\end{itemize}\n")
 end
diff --git a/src/Writers/MarkdownWriter.jl b/src/Writers/MarkdownWriter.jl
index ed6fa9ac5..eed14b1b5 100644
--- a/src/Writers/MarkdownWriter.jl
+++ b/src/Writers/MarkdownWriter.jl
@@ -120,7 +120,11 @@ function render(io::IO, ::MIME"text/plain", index::Documents.IndexNode, page, do
     for (object, _, page, mod, cat) in index.elements
         page = mdext(page)
         url = string(page, "#", Utilities.slugify(object))
-        println(io, "- [`", object.binding, "`](", url, ")")
+        print(io, "- [`", object.binding, "`](", url, ") (", cat)
+        if cat == :function
+            print(io, ", signature: `", object.signature, "`")
+        end
+        println(io, ")")
     end
     println(io)
 end