Swiftinit standard library + SwiftNIO API reference now supports multi-package typeahead search!

hi all, just an update on the entrapta-powered API references available at swiftinit.org!

note: all screen-recordings are live over-the-internet. no localhost cheating here!


a fast typeahead search

as i said in the last thread, my goal with entrapta has always been to build something that i myself would use in my normal development workflow. and for me, there are few features more important than a fast, integrated typeahead search.

you can navigate the typeahead options on desktop with the and -arrow keys. if you press Enter, it will follow the link to the highlighted result. the search menu is also mobile-friendly, and will not disappear on a touch screen when you dismiss the keyboard!

here’s a gif of the feature in action: (full size)

autocomplete-search-demo


fuzzy search

one of the issues with existing Jazzy (and DocC) search, is that the search is not fuzzy:

fuzziness-failure

entrapta search is fuzzy! in the screenshot below, ByteBuffer is spelled bytbuffer, and you still get the result: (full size)

fuzziness-demo


multi-package, multi-module symbol links

most existing documentation engines only support the single-module use-case. for example, in the screenshot below (from the existing SwiftNIO docs), the symbol IOData is not linked, because IOData lives in a different module from HTTPServerResponsePart.

this is not a problem with entrapta docs. as you can see in the GIF below, cross-module links work! you can even navigate through to symbols in a completely different package from where you started! (full size)

cross-module-link-demo

mobile usability improvements

Jazzy docs are not very mobile-friendly. (DocC is not so bad.)

in contrast, i’ve spent a lot of time ensuring the swiftinit docs are mobile-friendly. i’ve tried to layout the pages so that the most important information about an API fits above the fold on a mobile screen. here’s a real screenshot from my iPhone 11:

while not everyone browses API docs on their phone, these days about 60 percent of Google’s search users are on mobile, which means Google will not display pages in search results if the site is not mobile-friendly. because Google makes an effort to show the same results on desktop as they do on mobile, this means mobile-unfriendly API docs will also not show up in desktop search results. this is part of the reason why the existing SwiftNIO docs are so hard to find.

moreover, as i’ve been doing more work in places like libraries and coffee shops, i’ve actually found it surprisingly convenient to be able to browse API docs on my phone while working on a full-screen app.

what now?

if you are interested in the project and want to support it, the best way to do so is to bookmark the site and start using it in your day-to-day development, so we can get some more feedback based on real-world use cases. (it actually doesn’t matter which module you bookmark, because the typeahead search makes it so easy to jump to the module you’re looking for!)

you can also check out the github repository for the entrapta documentation engine.

enjoy!

10 Likes

Very cool! Nicely done!

Yeah, I definitely check API docs on my phone, and on my iPad. Responsive design is important to any modern website.

3 Likes

thank you! and yes, i’m continually surprised by how much is possible just through webkit on iOS Safari!

1 Like