Libdoc: Support searching keywords by name, arguments, and documentation

[pekkaklarck]

Especially with bigger libraries, it would be useful if Libdoc outputs had built-in search capability. It is possible to use browsers' search functionality, but it will search everywhere on the page. Dedicated search functionality could allow searching by name, arguments, documentation, and could show only the matching keywords.

Because Libdoc outputs is already now generated dynamically using Javascript, this shouldn't be too complicated to implement. We thus try to get it already into RF 2.8.7. Some kind of search functionality is a must latest in RF 2.9 when we plan to support keyword tags (#1840).

[boakley]

Can this be optional? For example, I use libdoc in robotframework-hub which already has a search feature built in. I don't want the documentation generated by libdoc to have a bunch of javascript or features that aren't easy to embed in another program.

[pekkaklarck]

Can you elaborate how search would make it harder to embed Libdoc outputs with other programs? These docs are already nowadays created dynamically using Javascript, so I cannot see how that could be the problem.

I'm not against making search optional. Just having a flag in the doc to not show the UI ought to be easy, but obviously you'd still have all the code there.

[boakley]

It doesn't make it harder per se, it's just that it makes the data
(arguably) unusable. The website that shows the libdoc data already has a
search box, so having a second search box on the page would lead to a very
confusing user experience.

What my code does is this:

from robot.libdocpkg.htmlwriter import DocToHtml
return DocToHtml(doc_format)(doc)

It then takes the return result and embeds that inside a div on a web page.
I don't want that div to include a search box, because I already have a
search box.

If DocToHtml hasn't changed, and the javascript is being tacked on in a
later step, it won't be a problem. Is that the case? Does DocToHtml still
just return the HTML, or does it return the HTML with the search box?

On Fri, Dec 12, 2014 at 2:53 PM, Pekka Klärck notifications@github.com
wrote:

Can you elaborate how search would make it harder to embed Libdoc outputs
with other programs? These docs are already nowadays created dynamically
using Javascript, so I cannot see how that could be the problem.

I'm not against making search optional. Just having a flag in the doc to
not show the UI ought to be easy, but obviously you'd still have all the
code there.

—
Reply to this email directly or view it on GitHub
#1872 (comment)
.

[pekkaklarck]

@boakley, no worries, there are no changes to DocToHtml. All changes will go to libdoc.html and libdoc.css.

[jussimalinen]

• The focus should move automatically to search field when I click the search icon
• Add an icon
• A keyboard shortcut

[pekkaklarck]

After the latest performance tuning I'd say this feature is ready to be released. We can enhance it in future releases. I'll leave this open for a little time and send mail to users list to ask for comments, though.

[rainmanwy]

Could the page scroll to the first matched line automatically, like the behavior of Browser's search?
I have tried the example "OperatingSystem.html". It has a long doc before keyword list(keyword list is out of my screen).
When i use "search" firstly, i though it not work because i could not see the filter result. Then i noticed it is out of screen.

[pekkaklarck]

We've been thinking about auto-scroll feature but weren't certain how it should work in practice. There are, at least, these questions:

• Should it scroll to the first match (i.e. beginning of the keyword table) as proposed above, or should it rather scroll to shortcuts where all keywords are visible.
• Should it only scroll when the search window is opened or always when search is done. In latter case it could easily scroll also when you wouldn't want it to.
• Should it scroll also to keywords or shortcuts regardless what part of the document is currently shown or only when the current location is above keywords/shortcuts.

If we can come up with a good answers to the above questions and implementation isn't too complicated, we definitely should do it for 2.8.7. Otherwise it's better to wait for the next release when we have more real life experience using the search.

[rainmanwy]

As i have seen, "Shortcuts" and "Keywords" part are included in search scope.
So personally, i prefer to scroll to first match in "Shortcuts" and "Keywords" part.

And about when, maybe after click "Enter".

Yes, i agree. May need more feedback.

[pekkaklarck]

@rainmanwy: After revision 1dffe84 opening search always scrolls to shortcuts section. That was easy to implement and seems to work fine. Scrolling can be fine-tuned in future releases if needed.

[pekkaklarck]

After the latest fixes and enhancement @jussimalinen and I consider this issue done.

[rainmanwy]

Ok, thank you very much!