A lot of web applications are written starting with code snippets and examples, modifying them to suit the requirements. Using third party libraries becomes very easy if they are supported with lots of examples. A good example is the
YUI page, where all components have examples that can be copied to applications for a start.
However, documenting these samples is hard for the API or library developers. Tools like
JSDoc or
YUIDoc generate pages that are not very helpful for programmers looking to pick samples quickly. These tools also do not contain live examples. The
Google API Playground is a great tool that not only has documentation, but also showcases working examples. However, using it for your libraries or APIs not very easy; you would have to set them up on Google App Engine and write tons of example files to get your sample working. This, IMHO, is an overkill for simple, CSS, HTML or Javascript APIs and libraries.
I wanted to write something that would be easy to use, and quick to setup. I repurposed a lot of old code to come up with such a tool. The project is called
TrialTool and has the following.
The guiding requirements for this principles would be
- For API and Library Developers and
- Should be easy to deploy. Backend server code should not be mandatory
- Writing examples should be easy
- The examples should be independent and able to run without the TrialTool
- Should be able to re-purpose existing code to show are examples
- For API users
- Users should be able to see examples
- Users should be able to see the documentation for APIs
- Pre-requisites, dependencies should be loaded in the example itself.
TrialTool is
hosted on Github and a sample trial example can be viewed at
http://axemclion.github.com/trialtool. The interface should be self explanatory.
- Top left page shows the list of examples
- Examples can be grouped as sets and can be dependent on other examples
- Example groups can be expanded, etc.
- The top right pane is the editor where code can be loaded
- This is based on codemirror and users can edit example code here.
- The bottom are can show the code output and the console.
- The tool bar at the top has the following buttons
- Run Snippet executes the code
- Load Pre-requisites loads other examples that the current examples is dependent on
- View Output / View Docs
- Clear Console
A
template file shows how an example can be created. Examples are grouped under sets and can refer to one another for dependencies. If you are interested in using this for your libraries or samples, I would be glad to help and you can
contact me.
To create your own set of examples, check this out. Follow
this space for updates on the project.