I’m building a Ruby API in Sinatra and publishing it’s documentation using Swagger. I didn’t really like any of the tools to generate swagger docs from the Ruby code so at first I was handwriting the JSON files myself. Then I decided that it would be easier to manage in YAML.
YAML was definitely a better solution than handwriting the JSON, but I was still wishing that the documentation for the models and API’s were embedded in the code they described.
I decided that the documentation would live with the code come hell or high water. I figured I could use Ruby’s block comments with a little bit of special formatting to identify documentation sections throughout the code base and lace them all together into one or more output files. The result is Richmond (named after the character in the IT Crowd who would have benefitted from some documentation telling him what all the blinking lights did).
After you install the gem, you can execute the gem from the command-line like so:
You can find the code for richmond on github, as well as additional documentation.