Release Notes
0.3.0
- Richmond was failing on binary files. Richmond can now be configured to ignore
or target specific files or directories via a .richmond file found in the root
of the directory being processed.
Configuration
Richmond will look for a file called .richmond in the root directory you are running against.
If it finds the .richmond file, it will load it.
You can use the select or reject methods to change which files Richmond will include or exlude
in it’s processing.
# Richmond doesn't like binary files
Richmond.reject do |file|
file.match /images/
end
# I only want to parse .rb files
Richmond.select do |file|
file.match /\.rb$/
end
The Context
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.
The Solution
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).
Usage
After you install the gem, you can execute the gem from the command-line like so:
richmond /dir/to/scan
You can find the code for richmond on github, as well as additional documentation.