Improve documentation of ActionView:RenderingHelper#render

[p8]

Motivation / Background

The current documentation RenderingHelper#render doesn't document all options and documents an the outdated :update argument.

The documentation of ActionController::Rendering#render is much more complete. It shows example code for the different rendering modes, has a separate section for other arguments and reads a lot better as well.

Detail

This change copies the documentation from ActionController::Rendering and updates it to make sense for ActionView:

• The response formats is replaced with formats.
• Removes the :json rendering mode, which isn't supported.
• The assigns, status and layout options are removed as the aren't supported.
• The :formats, :variants, and :handlers options are added.

This also removes the :update option which is no longer supported.

The following script allows reproducing the render modes and options:

# frozen_string_literal: true

require "bundler/inline"

gemfile(true) do
  source "https://rubygems.org"

  git_source(:github) { |repo| "https://github.com/#{repo}.git" }

  gem "rails"
  # If you want to test against edge Rails replace the previous line with this:
  # gem "rails", github: "rails/rails", branch: "main"
end

require "minitest/autorun"
require "action_view"

class Greeting
  def render_in(view_context)
    view_context.render html: "Rendering: renderable!"
  end

  def format
    :html
  end
end

class BugTest < ActionView::TestCase
  def setup
    @controller.append_view_path "."
    File.write("_partial.html.erb", "Rendering as html: <%= @name %>!")
    File.write("_partial.text.erb", "Rendering as text: <%= name %>!")
  end

  def test_supported_render_modes
    page = <<~ERB
    Test Render Modes
    <%= render 'partial', name: 'implicit' %>
    <%= render partial: 'partial', locals: { name: 'partial' } %>
    <%= render template: '_partial', locals: { name: 'template' } %>
    <%= render template: '_partial', formats: [:text], locals: { name: 'template' } %>
    <%= render inline: 'Rendering: inline!' %>
    <%= render body: 'Rendering: body!' %>
    <%= render file: '_partial.html.erb' %>
    <%= render html: "<script>alert('hi!')</script>" %>
    <%= render plain: "<script>alert('hi!')</script>" %>
    <%= render Greeting.new %>
    <%= render renderable: Greeting.new %>
    ERB

    puts render inline: page
  end
end

Which results in:

Test Render Modes
Rendering as html: !
Rendering as html: !
Rendering as html: !
Rendering as text: template!
Rendering: inline!
Rendering: body!
Rendering as html: <%= @name %>!
<script>alert('hi!')</script>
<script>alert('hi!')</script>
Rendering: renderable!
Rendering: renderable!

Checklist

Before submitting the PR make sure the following are checked:

• This Pull Request is related to one change. Unrelated changes should be opened in separate PRs.
• Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• Tests are added or updated if you fix a bug or add a feature.
• CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.

[willianveiga]

Looks good to me.

[skipkayhil]

I think if we want to switch the file to markdown we should go all the way, there are a lot of RDoc-isms left here (= header, <tt>, etc.)

(my suggestion would be to use tools/rdoc-to-md and then only commit changes to this file)

[p8]

Thanks! I ran tools/rdoc-to-md.

[p8]

@skipkayhil Do you think it's good to go now?

[skipkayhil]

Yes, looks great!

[p8]

Thanks @skipkayhil and @willianveiga !