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.
- 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
To create your own set of examples, check this out. Follow this space for updates on the project.