# Rails lack of documentation (render nested layouts)

**URL:** <https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538>\
**Category:** Rails\
**Created:** [September 2, 2008, 10:55pm UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538 "2008-09-02T22:55:52Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 2, 2008, 10:55pm UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/1 "2008-09-02T22:55:52Z")

</div>

I’ve posted some days ago about the lack of proper documentation for the  
testing framework used by Rails.

Today, among other days, I noted one more method missing documentation.

I’ve read the past year about nested layouts in some blog I don’t  
remember.

Today I had to write a new application and needed the nested layouts  
again.

First, I looked at the documentation, as I use to do. Didn’t find. Then  
I  
looked at my other project code and found how, although I couldn’t find  
this feature documented.

Into the documentation there are references for:  
render (ActionView::TemplateHandlers::Compilable)  
render (ActionView::TemplateHandler)

But none of them had any documentation available (although I’m not sure  
these are the methods I should be looking for. Maybe it should be  
“render  
(ActionController::Base)”).

Well, the requirements are quite simple, so is the solution, but finding  
it  
on documentations is impossible, unless I’m missing something.

To keep it clear, here is the actual case:

I want to have a master layout (application.erb) and another layout  
(another.erb) for the AnothersController, based on master layout.

application.erb:

... \<%= yield :further\_header %\> ...

another.erb:  
\<% content\_for :further\_header do %\>  
Further content here  
\<% end %\>

\<%= render ‘layouts/application’ %\>

Quite simple, don’t you think? So what am I complaining about? This is a  
very useful hidden feature. It is not documented. Even worse, the render  
method is not documented. And even if I didn’t care about others  
reaching  
this feature, I would care if this feature will continue working in the  
next Rails releases. Once a feature is documented, there is a great  
chance  
it will continue to be supported…

I would like to help documenting such missing documentation, but I need  
some  
instructions how can I do that: how to make patches, and need to know  
how  
do these methods actually work.

Thanks in advance,

Rodrigo.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 3, 2008, 8:21am UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/2 "2008-09-03T08:21:05Z")

</div>

On 2 Sep 2008, at 21:58, Rodrigo Rosenfeld R. wrote:

> render (ActionView::TemplateHandlers::Compilable)  
> render (ActionView::TemplateHandler)
> 
> But none of them had any documentation available (although I’m not  
> sure  
> these are the methods I should be looking for. Maybe it should be  
> “render  
> (ActionController::Base)”).

Which is there as far as I can tell:  
[http://api.rubyonrails.com/classes/ActionController/Base.html#M000848](http://api.rubyonrails.com/classes/ActionController/Base.html#M000848)

> application.erb:
> 
> next Rails releases. Once a feature is documented, there is a great  
> chance  
> it will continue to be supported…

Well the key thing is for there to be tests describing the  
functionality. Tests get automatically checked, docs don’t

> I would like to help documenting such missing documentation, but I  
> need some  
> instructions how can I do that: how to make patches, and need to  
> know how  
> do these methods actually work.

lifo’s docrails project on github is the place to go.

Fred

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 3, 2008, 6:40pm UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/3 "2008-09-03T18:40:37Z")

</div>

could not disagree more. but that’s another issue. 😉

On Wed, Sep 3, 2008 at 12:40 PM, Rodrigo Rosenfeld R.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 3, 2008, 7:24pm UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/4 "2008-09-03T19:24:37Z")

</div>

I agree with you that everybody would be benefited a lot if they know  
about  
unit tests. But a framework should not expect this from the end user. It  
should be up to (s)he to be enlighten…

Besides that, it is much easier to look for a feature in documentation  
than  
in the test units…

That is what I meant…

Rodrigo.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 4, 2008, 9:39am UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/5 "2008-09-04T09:39:53Z")

</div>

On 3 Sep 2008, at 19:28, Rodrigo Rosenfeld R. wrote:

> 

That’s not what I was getting at: What I meant that it is easy to make  
a small change that inadvertently changes how something behaves. At  
that point a unit tests guard against such inadvertent changes,  
documentation does not.

Fred

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 3, 2008, 6:37pm UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/6 "2008-09-03T18:37:06Z")

</div>

Frederick C. wrote:

> > documentation.  
> > find  
> > (ActionController::Base)").
> 
> Which is there as far as I can tell:  
> [Peak Obsession](http://api.rubyonrails.com/classes/ActionController/Base.html#M000848)

The documentation is there, but if it is the right documentation to look  
for, it doesn’t include description about the behaviour of specifying a  
string as the “options” param. It only describes action rendering and  
partial rendering.

> > application.erb:
> > 
> > next Rails releases. Once a feature is documented, there is a great  
> > chance  
> > it will continue to be supported…

> Well the key thing is for there to be tests describing the  
> functionality. Tests get automatically checked, docs don’t

This assumes everyone knows about test units. There shouldn’t be the  
case.  
The documentation should also state the supported features… A change  
patch  
should group the code change, the documentation change and the test unit  
change, when they apply…

> > I would like to help documenting such missing documentation, but I  
> > need some  
> > instructions how can I do that: how to make patches, and need to  
> > know how  
> > do these methods actually work.
> 
> lifo’s docrails project on github is the place to go.

Thanks for pointing that, I’ll look forward that.

Rodrigo.

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 4, 2008, 10:35am UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/7 "2008-09-04T10:35:06Z")

</div>

Hi Rodrigo:

I know a screencast from [railscasts.com](http://railscasts.com) that shows how to contribute  
to Rails with patches. In the example, the author contributes some  
documentation wich is precisely what you intend to do.

> **[\#50 Contributing to Rails - RailsCasts](http://railscasts.com/episodes/50-contributing-to-rails)**
>
> Short Ruby on Rails screencasts containing tips, tricks and tutorials. Great for both novice and experienced web developers.

Enjoy.

On Sep 2, 10:58 pm, Rodrigo Rosenfeld R. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)

---

<div class="post-metadata">

**Author:** ![dracko](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c89c15/32.png) [@dracko](https://www.ruby-forum.com/u/dracko)\
**Post date:** [September 5, 2008, 3:41pm UTC](https://www.ruby-forum.com/t/rails-lack-of-documentation-render-nested-layouts/147538/8 "2008-09-05T15:41:34Z")

</div>

Thanks, Abel. I’ve downloaded and watched it.

Frederick C. has also noted about lifo’s docrails project on github.

It seems more interesting, and now I’m playing a bit with git, before  
trying  
to contribute.

The next step is to understand the related source code. When trying to  
get  
the picture, I’ve found the following piece of uncommented code that I  
couldn’t understand. I tried to ask on ruby-talk newsgroup, but no one  
answered…

def templates\_in\_path  
(Dir.glob("#{@path}/ **/\*/**") | Dir.glob("#{@path}/\*\*")).each do  
|file|  
unless File.directory?(file)  
yield Template.new(file.split("#{self}/").last, self)  
end  
end  
end

That got me intrigued. What is the difference between  
Dir.glob("#{@path}/ **/\*/**") | Dir.glob("#{@path}/**")  
and just  
Dir.glob("#{@path}/**")  
?

Thanks,

Rodrigo.