Add support for direct method lookups in search

[voldenet]

It would be nice if search for Array.push would get to the https://docs.raku.org/type/Array.html#method_push directly.

[lizmat]

On that note:

$ raku -e 'say &push.WHY'  
No documentation available for push.  Perhaps it can be found at
https://docs.raku.org/routine/push.html

I guess that could be made smarter for methods:

$ raku -e 'say Array.^find_method("push").WHY'
No documentation available for push.  Perhaps it can be found at
https://docs.raku.org/routine/push.html

hmmm....

[lizmat]

Looked at doing that, but finding the package from a Method object turned out to be too difficult.

[finanalyst]

the search candidate data (which is then filtered to show a list on screen) is built from the document sources. If the relevant method is described in a Type/document eg (Type/Array.rakudoc) with a heading "=head2 method push" then it is included in the composite file for push. my guess is that such a heading doesnt exist. that then is a content problem. if such a heading does exist, but is not in the search bar, let me know because that would be a bug in the doc-site plugin 'secondaries'. content not showing up is a build problem.

…

On Thu, May 11, 2023, 12:29 Elizabeth Mattijsen ***@***.***> wrote: Looked at doing that, but finding the package from a Method object turned out to be too difficult. — Reply to this email directly, view it on GitHub <#253 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACYZHEEDQTZCG5W5RQYAVTXFTETBANCNFSM6AAAAAAX42VTNM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[finanalyst]

@voldenet I tried searching on push, which gives several candidates, including the fact that it is in the documentation on Type Array. But it can also be used for a Hash. All of this information is contained in the search bar. So closing.
If the request is a form of 'Do What I Mean', a clearer generic request is needed.
Please reopen this request if a generic way to DWIM in the search bar can be suggested.

[coke]

The original ask, a way to search for the specific method, still isn't done, and I think is a worthwhile ask. The workaround (search for push, pick the right one) is a workaround.

[finanalyst]

@coke How would this look generically?

If a search is made on push, all the Types that provide push are listed?

If a search is made on Array, all the methods are listed?

So generically, searching on a method name yields all the Types that provide it, and searching on a Type name provides all the methods it provides.

I suppose that is what the Type and Routine pages were intended for. I have never found them useful.

[patrickbkr]

I noticed, that @voldenet wrote about searching for Array.push, while @finanalyst wrote about searching for push or Array separately. Is there some misunderstanding here?

[coke]

IMO, one could search for .push and that should return the combined page as the top result.
Something like push might have a large number of individual hits. We could discuss if they also should need in the result list and what order.

Class.method should return the specific result as the top result

[finanalyst]

@patrickbkr I closed this issue orginally, thinking that it was not really a doc-website problem, and more of a Raku/doc content problem. The information that @voldenet specifically requested was included in the list of candidates by search, which I had improved between his original request and when I closed the issue.

@coke re-opened it because a search on push produced lots of candidates, but not a specific Array.push.

So I am trying to figure out what search strings should produce which results. I remain a bit confused and so I can't figure out how this issue could be closed.

[coke]

I thought it was clear what the ask was.

Is there a way to write tests to run with the build that can compare search results with query strings? If so, I can write tests to cover the cases.

[finanalyst]

@coke @voldenet @patrickbkr @lizmat Currently Search is a filter on a list of candidate structures and selects only those that match or fuzzy-match the search string and the value part of a candidate.
A value of Array.push does not exist, so a Search will not find a useful candidate.
Suppose we say that a space, eg 'Array push' will filter candidates that match both 'Array' and 'push'? and also extend search to the 'Info' part of a candidate.
The problem I see with 'Array.push' is that . is used often in the value part (typing . into the search bar yields 106 candidates)
Is this an approach we could adopt?

[patrickbkr]

@finanalyst

Do we have syntactic support for establishing the connection of =head2 method push and =TITLE class Array? It seems that currently "method push" is simply a free text that happens to mention a method name. Equally "class Array" is a free text that happens to mention a class name. To reliably introspect this information we would need to provide some syntax that we can depend on. There is =begin pod :kind("Type") :subkind("class") :category("composite") at the top of the file, which gives context that the file is about a class. Not sure if the info which class it is about is available.

Or is there a convention that says that if a =TITLE text matches class .* is seen we are talking about that class and if a =head2 text matches method .* we are talking about a method of that class?

I'm a bit out of the loop with respect to the capabilities of rakudoc, but something like =head2 push :kind("method") would be nice. Syntactic sugar =method push would be even nicer. Same for class.

If we have that high-level information available (this file talks about the class "Array" and this section talks about a method of that class with name "push"), then we could automatically add an index entry: Array.push.

[finanalyst]

@patrickbkr tl;dr Your suggestion would require a fairly fundamental re-write of the Documentation suite. I think that's possible, and I'll respond in more detail below.

To address the suggestion, I think some extra information is needed (apologies if this is already known, but restating it may help if I have misunderstood your suggestion).

• The Raku documentation suite (that is everything under repo Raku/docs/doc/ ) contains around 500 files in RakuDoc format, each of which start =begin pod :kind<method> ... as you describe.

• Some RakuDoc related things:

  • the item :kind in the =begin pod line is called a metadata option.
  • RakuDoc allows for all blocks (such as =head1 =para =item) to have metadata options, but the syntax needs to be of the form =begin head :kind<method>, and not =head .... This is because we need to distinguish between what appears in the final render from side-effect information (that is what is in metadata options), which do not appear explicitly in the final rendered form.
  • So 'yes' meta data can be associated with every block.
  • A renderer will gather information about blocks to create a Table of Contents
  • A renderer will gather information marked up with X<> tags to create an index.

• Some Raku documentation related things

  • Before any file in the Raku documentation suite is rendered, it is parsed by the site generation software.
    • In the past, this site generation software was called Documentable, but now it is Collection
    • The site generation software creates the HTML page, and adds the Table of Contents,
      • Documentable never added an Index. Collection can add an index - perhaps I should show how to do this.
  • The site generation looks for =head blocks that match a regexe, which picks out keywords such as 'method', 'infix', 'sub', etc.
    • If the regex matches, the keyword is used to create a new documentation file (which I call a 'composite')
    • The idea is that if the same method (eg., say) is specified by different types, then there will be a single file listing each of the Types.
    • In addition, some =head blocks are also marked up with X<> formatting. Eg. =head X<Some method|Syntax; make this into a composite file as well>
  • The information gathered to create composite files, the data in the Table of Contents, and the data accumulated for the index is then all used to create a list of 'search candidates', which can then be examined with the 'search' functionality added to each HTML page.

• My suggestion was rather to change the way the search function manages the candidate information, rather than to change the source files.

So to respond to your suggestion: We already have a ponderous system for gathering search information from the source files.

• There is a considerable amount of information that is gathered, but is not directly used (eg. the name of the origin, and its TITLE) could be added to the seach candidate structure and used in the search engine.
• It would be possible to add to that system by adjusting the regex, or extracting more information

It would be possible to add metadata to each =head block, but that would require a fairly extensive rewrite of the documentation.