swagger-to-html, Bootprint, Customize

This was the reply to a github issue, but it actually didn't belong there.
Somehow I felt I shold tell the whole story of Bootprint...

I was looking for something to document our REST-services at work and stumbled across Swagger and the Swagger-UI. Swagger-UI is great and we are using it, but it's nothing you can print out or give to someone offline as service-reference. So I had a look and found Swagger-Codegen which can create client code for a Swagger-Spec in different languages. It can also create HTML. But when you look at the usage instructions, this is nothing, the average sales-person can use to generate an API doc. You have to install Maven and run a pretty complicated command-line. I was using it for the first version. But then I thought: How hard could it possibly be. A simple Handlebars-setup, a simple Less-setup, include Bootstrap write some templates. Done. Two hours of work... I thought. And started swagger-to-html in my free time...

Turns out that it took a little longer and the scope got a little larger. Because, of course, you want to be able to customize the styles to use your company colors. And how cool would it be, if you could publish a customization-package and let other people build upon it.

This was the moment, when I seperated to code from the template and made different packages: bootprint, bootprint-swagger, bootprint-json-schema which build upon each other. Making another adaption should be easy.

But it doesn't stop there, because bootprint-swagger got some stars. I got bug-reports (which is pretty cool, because it shows that other people are actually trying to use this module) and of course, I want bootprint-swagger to be comprehensive. But I'm doing this in my free time and this often means working on it late at night, when the family is asleep. This is certainly nothing I can do forever, so the best way is to document the project in order to enable people like you to do the work for me and make pull-requests.
But documentation is a hard thing and the danger of out-dated documentation, so I'd need tools to embed the documentation somewhere inside the code and assemble docs from it.

After doing some research on npm, I stumbled across verb by Jon Schlinkert, which uses lodash-templates to transform a package.json into a README.md and much more. This project is certainly worth a look, but after some experiments I thought: Maybe Bootprint without Less could be used to create flexible and customizable templates for generating Markdown files for npm-module. So I extracted the config-merging part of Bootprint into a new project called Customize, added a Handlebars-plugin and used this to create the documentation generator Thought.

After a while I noticed, that at some point, you have to document my documentation-generating tools. So this is what I'm actually working on at the moment. Writing documentation, thereby extending Thought. I'd love to see other people use Thought as well, but at the moment, it's pretty experimental and nobody seems to have taken notice of it yet.

When I'm done with this, I plan to create Less-engine for the customize-project and migrate Bootprint to use Customize as well. But that's a long path. Customize does not support file-watchers yet and that is essential when developing Bootprint-templates.

The idea of being able to override parts of the configuration (replace partials, adapt styles) is part of our day-to-day business at work. We often have things like that in our products. It's not a new idea for me.