Embedding Middleman in a gem?

#1

Hi, I’ve used middleman for various projects in the past and love it. I’m now building a gem that lets you generate your HTTP API web documentation via a ruby DSL.

How it would work is my gem would load the user’s API definitions, which creates a ruby data structure that represents your API resources, params, response properties, etc. I would want to load this into middleman and use that as data to render web documentation.

I would like to use middleman to manage assets, build process, structure, and deployment for the user. I thought about creating an extension that adds a new :api_doc template, but I want my gem to house the page definitions, erb/haml/slim templates, and assets because my DSL could change, and if I did this as a template, then they would have to regenerate the project to get updates, which might mean losing their customizations.

Any suggestions on how to accomplish this?

#2

I’ve managed to mostly accomplish this by putting the config.rb and source files into a doc directory in my gem and then setting ENV['MM_ROOT'] to this directory. Then I use Dir.pwd to load the api files. This actually works.

Now I’m trying to figure out how to load an external config.rb file so the user can add their own config options in additional the config I have set in my gem.

#3

I found your project on Github: https://github.com/kamui/kanpachi

Looks like a neat example on how you can build a documentation tool around middleman.

#4

Thanks! The main difficulty has been trying to find a way to wrap or delegate middleman’s Thor tasks. I need users to be able to do kanpachi build instead of middleman build, since i need to rewrite the MM_ROOT path before calling build. This hasn’t been so easy b/c of a combination of Thor weirdness (or maybe my inexperience, but the docs aren’t so great) and the way middleman uses method_missing to direct subcommands and classes for each subcommand. I kind of wish the implementation of the Thor tasks were contained in standalone classes/methods, and then all Thor tasks would just call these. Then it would be easy to write your own Thor or rake tasks to call middleman subcommand functionality.

Just being able to set middleman’s config path (instead of looking for config.rb in MM_ROOT) would have been really nice.