Rails core - Apr 2010 - 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
(http://wiki.github.com/lifo/docrails/rails-api-documentation-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).

-- 
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Core" group.
To post to this group, send email to rubyonrails-core@googlegroups.com.
To unsubscribe from this group, send email to
rubyonrails-core+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/rubyonrails-core?hl=en.

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 <http://wiki.github.com/mislav/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.

-- 
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Core" group.
To post to this group, send email to rubyonrails-core@googlegroups.com.
To unsubscribe from this group, send email to
rubyonrails-core+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/rubyonrails-core?hl=en.