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)
fuzzy search
one of the issues with existing Jazzy (and DocC) search, is that the search is not fuzzy:
entrapta search is fuzzy! in the screenshot below, ByteBuffer is spelled bytbuffer, and you still get the result: (full size)
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)
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!