NY Standup: Documentation interpolation and RVM, Brew and autolibs FTW

Robbie Clutton

Tuesday, April 2, 2013

Interestings

Grant Hutchins / David Lee

If you wrap the opening name of a Ruby heredoc in single quotes, its insides will act like a single-quoted string.

If you wrap the opening name in backticks, the heredoc will be immediately executed through system()

<<-HEREDOC
1 + 2 = #{1 + 2}
HEREDOC
=> "1 + 2 = 3\n"

<<-'HEREDOC'
1 + 2 = #{1 + 2}
HEREDOC

=> "1 + 2 = #{1 + 2}\n"

<<-HEREDOC
uname
date
HEREDOC

=> "Darwin\nMon Apr 1 17:50:43 EDT 2013\n"

Found at http://jeff.dallien.net/posts/optional-behavior-for-ruby-heredocs

rvm autolibs

https://rvm.io/rvm/autolibs/

In the latest versions of RVM, you can have RVM build dependencies automatically for you. For instance, if you use Homebrew, you can run

$ rvm autolibs brew

and from then on, RVM will automatically build any packages it needs via Homebrew.

As always, read "brew doctor" to get more info about how to set up your particular system.

A Great Example of Vendor-Library Abstraction in ActiveSupport

Mark Rushakoff

Monday, June 18, 2012

Depending on what you’re working on, you may have been bitten at least once by a heavy dependency on a third-party library.
This happens when you become very dependent on the API of someone else’s library, and suddenly you can no longer use that library or its API.

When this is a possibility, the defensive approach to this problem is to write your own API to wrap that API, so that if you need to drop that vendor library, you only have to reimplement the way your wrapper works.

You might think that you only need to worry about this in large, complicated APIs, but it can be worthwhile to do even for a simple API.

ActiveSupport::JSON uses MultiJSON behind the scenes.
Even though ActiveSupport::JSON has really only two publicly available “normal-use” methods (encode and decode which transform Ruby hashes back and forth with JSON objects), the Rails developers were wise enough to even wrap the specific error class that MultiJSON raises, as ActiveSupport::JSON.parse_error.

# File activesupport/lib/active_support/json/decoding.rb, line 50
def parse_error
  MultiJson::DecodeError
end

This way, you can write something like

begin
  obj = ActiveSupport::JSON.decode(some_string)
rescue ActiveSupport::JSON.parse_error
  Rails.logger.warn("Attempted to decode invalid JSON: #{some_string}")
end

And then if/when Rails switches from MultiJSON, you won’t have to change anything in your code to deal with exception handling around JSON.

(PS.
I wrote the documentation for that method recently, so that’s why I had to link to the Edge Guides.
If you haven’t seen it, check out my article on how easy it is to contribute to the Rails documentation.)

Executable Documentation

Will Read

Sunday, June 3, 2012

I try to avoid writing static documentation. It gets old and out of date as soon as the next person comes along because it is logically far away from the code it describes, so event the best intended developers won’t always be aware of the documentation dependencies. Since working at Pivotal I’ve enjoyed writing tests first with RSpec, which results in one form of executable documentation to describe behavior to other developers working in the code base. But what about when you need to express behavior to people outside of your code base? Maybe your stakeholders have a company requirement of documentation, maybe you’re trying to entice third party developers to use your new HTTP API, or maybe you just want people to install your gem, what then? Your audience matters, and there’s a variety of tools out there to use depending on your needs.

Human Readable

Cucumber is one tool that can be used to fill this need. It’s designed to be a DSL for creating DSLs to describe your application. It has a nice attribute that it is very human readable. You can then use tools like Relish to publish docs from your Cucumber suite. The drawback is that you put a lot of effort in to expressing what you want in English, which is great if you’re really showing this to non-technical people, but it can be an over optimization if your readers have some technical context.

Dev Readable

In the case where your audience is an outside developer, something like rspec_api_documentation might be more appropriate. It layers on a DSL to your familiar RSpec DSL that lends itself to HTTP APIs. This is great because your RSpec tests become more expressive without the overhead of defining the DSL yourself. From there, you run a rake task to generate HTML. Your spec runs will fail if your docs get out of sync, which should be never if you have CI. The web is an easy venue to consume this kind of information, but the tool doesn’t let you editorialize much beyond the description of the resource and the parameters.

The Best of Both Worlds

One of our open source projects here at Pivotal Labs is Jasmine, a JavaScript testing framework that runs in the browser. Unlike Rspec where you need to have ruby installed and a database set up and so on, everyone has a browser. Check out the jasmine docs and scroll to the bottom. That’s right, the examples are tests, the comments are close to the tests so when the test fails you know to update the text as well, and now someone has a working example of how to use Jasmine all in one. The page itself is generated using Rocco, a Ruby port of Docco.With the combination of docs generated from tests, and tests that run in the browser you get this perfect blend of readable, easy to maintain documentation that is available to your entire audience.

Sometimes you have to provide documentation, but that doesn’t mean it has to be outdated. By creating executable documentation you can have confidence that the code and docs are staying in sync. Consider your audience carefully when choosing how you will document your software and know that there are more than a handful of options available, one of which will probably suit your task well.

They practically couldn’t make it easier to contribute to the Rails docs

Mark Rushakoff

Monday, April 30, 2012

If you ever spot room for improvement or an error in the Rails documentation — and that includes the Rails Guides and the API docs — they’ve made the process extremely easy. If you’ve been waiting for “the right moment” to start contributing to open-source software, this might be it.

The docrails project on Github, has public write-access enabled so that anyone can push documentation fixes.

This Rails blog post goes into full detail on the docrails project, but here’s the short and sweet version:

Never touch any source code in commits that get pushed to docrails. If you need to change code, make a pull request to the main Rails project. docrails is for changes to RDoc, guides, and README files.
docrails will occasionally be merged into rails, and vice versa. docrails has maintainers who ensure that no “poor” commits to docrails make it into the rails repo.
If you’re confident that your documentation fix is an improvement, just push to docrails!

If you want to expand (or just start) your “open-source portfolio,” docrails is a great place to begin.