I’ve written before about my appreciation for good application documentation, especially for explaining the nuances of domain logic. I was disappointed that support for generating a nice, HTML-formatted documentation was removed in Rails 5. Luckily, it’s not too difficult to reimplement this feature in an app, and customize it to your team’s documentation needs.
First, add the
sdoc gem to your Gemfile, and run
bundle to install it. SDoc is the same library that was bundled in previous versions of Rails. With SDoc installed, you can once again generate application documentation from the command line:
Then open doc/app/index.html to check it out. Unfortunately, it’s pretty messy right now. SDoc provides a lot of configuration options to tidy things up (see
sdoc --help), but it would be better to set those configurations once. While we’re at it, it’d also be nice to restore the ability to generate the docs via a Rake task.
Use the task generator to create a new namespace:
Locate the new file at lib/tasks/doc.rake, and add your documentation configuration. You can start by pasting in the sample code from the SDoc documentation:
This adds three Rake tasks related to documentation:
rails rdoc, then open doc/rdoc/index.html in your browser to take a look at the results.
The output is still pretty noisy. The task still tries to document the entire Rails project directory, including tests and the public directory. It also uses the Gemfile as a default page, instead of the README.
You can tidy that up in the new Rake task file. SDoc is a wrapper around the RDoc documentation library, which itself is well documented (of course). The interesting parts for this exercise are in the
To focus your app’s documentation on application code only, try:
rails rerdoc to regenerate the files, and open doc/rdoc/index.html again. Much nicer! Now the documentation defaults to the project README, and only application code is included in the output.
One last tweak: Documentation support in previous versions of Rails wrote out to the doc/app directory. This can be set with the
Wherever you wind up saving your documentation, I still recommend including that directory in your project’s
.gitignore, to avoid repository clutter. Also, tell contributors how to generate and view the application docs in the project README. Aside from having to roll out documentation support independent from the framework, the rest of my documentation workflow still applies.
This is still a work in progress for me, but I’ve been happy with the results so far, using this simple configuration. If you’ve found alternatives that you like, please share them in the comments. Thanks for reading!
Thanks to Sebastian Röder for suggesting this topic.
I stand with the Black community against systemic racism, police violence and brutality, intolerance, and hate in the United States and worldwide. We must all demand better from our leaders, and ourselves. Stop tolerating intolerance.
While you're here, please consider making a donation to Black Girls CODE, who do great, important work to provide opportunity to underprivileged girls interested in tech, or any organization working toward equity and safety for all, not just the privileged. Thank you.
If you liked my series on practical advice for adding reliable tests to your Rails apps, check out the expanded ebook version. Lots of additional, exclusive content and a complete sample Rails application.
Ruby on Rails news and tips, and other ideas and surprises from Aaron at Everyday Rails. Delivered to your inbox on no particular set schedule.