mjl > sherpa > api documentation
Intro | API documentation | sherpa.js | Specification | Implementations | FAQ | Why

Why documentation?

Documentation is need to use an API properly. It's important, but it takes a lot of time to write, easily gets out of sync with the code, and requires effort to publish.

Not with Sherpa. Of course, you still need to write documentation. But it is kept right with your code, making it easy to keep up to date. And you don't need a separate tool to generate documentation. Or setups to serve the documentation. That's all provided automatically by the sherpa library for your programming language.

Example documentation

An example of sherpa documentation can be found at:

sherpa.irias.nl/#https://sherpa.irias.nl/example/

How does it work?

Sherpa API's provide their own documentation through a simple mechanism. Here is how it works. An API simply exports a function called _docs. It returns documentation in a simple JSON format, with text in markdown.

Server libraries help you deliver this documentation as part of your API, by using comments from your source code or through code annotations.

How do I read documentation

Using sherpaweb. Sherpaweb is a simple web app that lets you easily read this documentation and lets you find your way around the API by letting you call functions and displaying the results. It's pure html/javascript.

A public sherpaweb instance is running at:

sherpa.irias.nl

Running your own sherpaweb is also easy: Use the pre-compiled stand-alone binary (it just serves the static files), or take the html/js from source. Remember that your browser reads and renders documentation, so you can use the public sherpaweb for your internal/local API's as well.

Download

The following binaries are available:

Code

Sherpaweb is MIT-licensed, maintained at bitbucket.org/mjl/sherpaweb/ using Mercurial. It's written in Go. See the README on how to compile.