Search tools for API documentation
Friday, 10 June 2011 23:33
Continuing my quest for the perfect API documentation, this week I came across a site that offers a search over a set of API documents: Rails Searchable API Doc. Have you seen it before, or anything similar or even better?
I’ve written a couple of posts recently about API documentation, talking about documenting REST APIs and using tests as examples. People have added a lot of very useful and thought-provoking information via comments on both posts. Thank you everyone! This time, I’d like to show you a site that Jean-Michel pointed me at.
sdoc for searching Ruby APIs
The Rails Searchable API Doc site is developed by Vladimir. As the name implies, you can use the site to search the Ruby on Rails API documentation. The site is built by Vladimir’s tool sdoc, that adds a search feature into the documentation generated by RDoc. RDoc builds HTML documentation from Ruby source code.
Vladimir’s sdoc code repository is on Github. Here’s the readme.
Try it out!
Go to http://railsapi.com/. Here’s the gist of what you will see:
Rails Searchable API Doc
Select one of the options above the big buttons, to choose the APIs that you want:
- Rails
- Rails and Ruby
- Build your own
If you choose to build your own, you will get a list of APIs to choose from:
Rails Searchable API Doc - select your APIs
Make your choice, click “Browse online” to see the API documentation, then enter a search term to see the dynamic search working. It’s in the left-hand panel:
Rails API search
What I like about this search is that it’s immediate. You see the results as you type. A very nice addition is that you can select one or more sets of API documentation to merge into the search.
The search is smart. The first few results show matches that start with the search term you entered. Then come the results where your term is embedded somewhere in the string. Finally it shows results that may be a match: the characters in your search term appear in the result, but not necessarily sequentially. The front page has a quick guide to the features of the search tool.
Pretty neat, huh.
I want an sdoc!
I’m wondering how much sdoc relies on the RDoc format, and how easy it would be to adapt it for documentation generated by other tools such as Jersey’s WADL generator, Javadoc, Sandcastle for .NET, Doc-O-Matic, Enunciate, Doxygen. I’ve written to Vladimir, asking him for his thoughts on this.
Have you seen similar search tools on other API documentation sites?
BTW, a good API doc site
This is nothing to do with searching, but it is part of the quest for the perfect API documentation. Daniel is a fan of the Facebook developer portal. I’m impressed too.
Read more http://ffeathers.wordpress.com/2011/06/11/search-tools-for-api-documentation/
