Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
fingolfin opened this issue Jun 13, 2019 · 5 comments
Open

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

fingolfin opened this issue Jun 13, 2019 · 5 comments
Labels
Format: HTML Related to the default HTML output help wanted Type: Enhancement

Comments

@fingolfin
Copy link
Contributor

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
Copy link
Contributor Author

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

@ThomasBreuer
Copy link

ThomasBreuer commented Jun 23, 2021

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
Copy link
Contributor Author

fingolfin commented Jun 23, 2021

@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
Copy link
Contributor Author

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 fingolfin changed the title Methods in search results should display signature Methods in <s>search</s> index results should display signature Jul 9, 2021
@fingolfin
Copy link
Contributor Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Format: HTML Related to the default HTML output help wanted Type: Enhancement
Projects
None yet
Development

No branches or pull requests

3 participants