Improve docs

[rosylilly]

You can preview this. Let's access https://crystal-doc-new-design.herokuapp.com/ .

• More contrast on sidebar
• No expanding animation on types list.
  • This is not important animation. but this is interfere when changing pages.
• Fixed arrow issue on Firefox w/ Linux, probably.
• Expands module on clicking.
• Searchable Methods List by [API doc browser] Method index/search #1792
• Fuzzy Search(Alpha) by [API doc browser] Implement fuzzy search #1791
• Keep search words when changing pages by Improve API docs search result tree (expanding/collapsing) #1621
• Smartphones ready(Alpha)

Preview images

Fuzzy Search

Method Search

Smartphone

[adlerhsieh]

Looks great!

[asterite]

@rosylilly Awesome!! Looks really nice :-)

I really like the method list, showing the type it belongs to below it.

I have some comments:

1. I don't find "fuzzy search" very useful. For example I search "base64" and "OpenSSL::DigestBase" also comes as a result. In the method list it becomes even less useful, I search "concat" and I get "combinations", "truncate" and other results which are definitely not relevant. Instead of "fuzzy search" I would just compare case insensitive and maybe inclusion in the target (target.downcase.includes?(search_value.downcase)) or something like that. Or maybe the fuzzy search needs to be adjusted, if it uses levenshtein distance in the compiler the tolerance is max(1, number_of_chars / 5) so for short words you usually show results that are within one character distance, and longer strings allow for more errors (although I search "semd" and I don't get "send" as a result, so maybe it's not using levenshtein distance). If fuzzy search remains, I would make it be turned off by default.
2. If I disable "fuzzy search" and then click on a method or type, after the page loads the "fuzzy search" is active again
3. If I have the Methods tab selected and I click on a method, when the page loads the Types tab appears selected and then the Methods tab becomes selected. It would be nice to somehow prevent this.
4. If I click on a method on the right side, going from the summary to the detail, and then I scroll up and click on a different method, I end up in the same method as before (the anchors seem broken). In fact, if I click on any link in the right hand side, it always scrolls to this old anchor.
5. If I search "gets" on the Methods tab (without fuzzy search) there are many "same" results for IO. This is because there are many overloads. Maybe just show one and when you hover on it show the overloads (for example see File and search with the browser "gets", the hover it). This is something optional to do, the current way is fine but could be improved.

[asterite]

Oh, and a separate issue that is a bigger concern: generating the docs for the compiler now takes 22s instead of 1.5s. For another project I have the time went from 0.72s to 2.4s. Do you see an obvious reason for this performance decrease?

[asterite]

Hmm... the performance decrease seems to come from the huge increment in the size of files. Base64/Error.html used to be 2382 lines, now it's 40351 lines. Is there some way we can avoid this increase?

[ysbaddaden]

Fuzzy search is useful when having a few letters off (bcrt => Crypto::Bcrypt), or typing just some letters or each namespace (digmd => Digest::MD5).

Yet, it would play better with a flatten list of types, and by returning exact matches first, then fuzzy (with matching text in bold).

I don't think the tree is any useful anyway. I'd really prefer a flat list of "Crypto::Bcrypt" than having to click on "Crypto" that reload the whole page, which always make me click somewhere else than I intended next, or try and hit the tiny arrow to search for something...

Ie. I think http://api.rubyonrails.org got it right.

[ysbaddaden]

Page size increase: it pushes methods along with types, and its duplicated on each and every page.

Either we return to iframes (but we'd lose the per-type URL), or we generate each page twice: once with the types and methods, and another one without. Loading the page loads the full page, clicking a link fetches the light page throught XHR, updating the DOM, the URL history, and the page title.

[rosylilly]

Thank you for reviewing.

but, I'm busy. Please give me some time.

[asterite]

@rosylilly Sure, take your time :-)

@ysbaddaden I also think some sort of ajax and having the data in json in some file will eventually be the solution to reduce the amount of hardcoded text.

I also wouldn't mind at all doing this with [the recommended JS library/framework of these days]. Writing vanilla JS is no fun.

[refi64]

[the recommended JS library/framework of these days]

That would likely be React, but I personally find it overkill for this situation. What about jQuery, with CoffeeScript if you don't like JS's syntax?

[jhass]

I agree that fuzzy search by default is good thing. To make it work well one needs to sort by the best match first though (eg. the smallest levensthein distance at the top), results with the same score should be sorted alphabetically in their category. That would automatically put exact matches at the top.

[asterite]

I think eventually the best thing to do, maybe, is to generate a json file with all the data and let a user browse them, using javascript. This will make the docs really compact, and searching content should be very easy to do. I'm closing this for now.

[rosylilly]

I'm agree.