the main source of API docs is master

I've seen some confusion regarding the role of docrails with regard to the API. Many people have the impression that documentation goes through docrails, but this is not exact. Let me share these remarks with you all:

The main source of API docs is master.

When a patch to master adds stuff that belongs to the public interface, the patch should include proper tests and rdoc. You do not send the code through master and then document in docrails, rather everything goes in the original patch for it to be complete.

If the patch renames/moves/deprecates/... the source tree would be additionally ack'ed to find instances of the previous idiom. The examples in the API docs have to implicitly show what is idiomatic in modern Rails to the reader and may need update. That goes also with the patch.

It is difficult to have a global uniform style with contributions by so many people (we're approaching 1500!), or that everybody follows precisely the API conventions (, and so it could be the case that someone in the doc team then copy-edits a little, but that is minor in general.

So, what about docrails? The purpose of docrails is to be able to *patch* the docs bypassing LH. For example, if you see an error in the API and you have commit in docrails (otherwise ask lifo), you just fire up a console, edit, and push. Fixed.

Since going through docrails is just a shortcut for something that would go trough LH otherwise, merges from docrails into master are now normal and Rails Contributors gives you credit, as if the doc patch went through master (though if several trivial commits are pushed it could be the case they get squashed to keep some balance).

I’d like to jump in with a heads-up to people testing documentation they’ve written or generating edge docs for themselves: while making a new template for Rails 3 docs (porting Hanna to RDoc >= v2.4) I’ve discovered a number of bugs in the latest RDoc release (v2.5): the biggest bug being that a large number of methods are never present in the final output as well as missing extra files like CHANGELOG or README.

The last release known to work was RDoc v2.4.3. Example of using it through rubygems:

$ cd activerecord

$ rdoc 2.4.3 --main README CHANGELOG README lib

It will render docs with RDoc’s new default template, which is good enough for testing purposes. To render only a single file, specify it in the file list instead of “CHANGELOG README lib”.

Hope this is useful to somebody.