[RF-DOCS] Action Mailer Guide [ci-skip] (rails#52905)

Here are some of the things addressed for this Guide.

- Mailers now actually inherit from a generated ApplicationMailer, which in
  turn inherit from ActionMailer::Base.
- The output to generating a mailer might be different depending on whether the
  base ApplicationMailer and layout have already been generated, which will
  already happen when creating a new app, or if they're not there the first
  time the mailer is generated.
- Maybe the generator should be shown by passing an action name directly? (or
  as a second example or subsection?) bin/rails generate mailer User
  welcome_email
- Complete List of Action Mailer should be linked. (in fact, maybe we don't
  even "need" this to be a section, but rather part of the text when
  introducing the other mailer methods? And then a full section on Attachments)
- The HTML view has a complete layout with DOCTYPE/head/body, but it should be
  using the application mailer's layout, so that example will likely double the
  HTML, it is incorrect.
- The guide shows how to build a multipart email (HTML + Text), but doesn't
  really explain why, what are the benefits, if it's really needed, etc., might
  be a worth addition to consider. There's a section later in the guide that's
  about "multipart emails", that we could link to from the top, and perhaps
  expand a bit on that.
- I wonder if we should instead show an example of sending the email via
  console, after we have the mailer and associated model? And then proceed with
  showing the controller version.
- Link to Active Job guide, there's a mention when explaining how to call the
  mailer, and a Note. That note should likely be simplified and linked instead.
  (less duplicated content, no need to mention Sidekiq,etc. elsewhere, etc.)
- If we do show how to use via console, it'd be a good introduction to start
  with deliver_now, and then explain deliver_later + Active Job afterwards.
- Auto Encoding Header Values seems like a topic/section that could be pushed
  down, it's not a common need. Decided to remove as it is an extraneous
  detail.
- Attachments could be a larger subsection, right now it's a 3rd level section
  that doesn't show in the sections list on the right.
- "Action Mailer 3.0" no need to mention older versions any longer.
- Under the Layouts section, it doesn't mention where the layout should be
  located. (app/views/layouts), and it should probably mention the default
  mailer layout now too. (see other comment about about the email template
  containing the full HTML tags)
- There's a section about "Dynamic Delivery Options" that shows how to pass
  SMTP & etc. configs, but the configuration section is later in the guide,
  this could be reorganized to better flow, or at least linked.
- There's some information about views, layouts, rendering without a template,
  etc., scattered, maybe it makes sense to group these related pieces a little
  bit better.
- Under the configuration section, deliveries is not really a configuration but
  something to use in dev/test., not sure it's where it should be mentioned.
- A new section about rescuing errors could be added too. [Here's the
  API](https://github.com/rails/rails/blob/3efae445196da943c0532a00f6dfbafc74ae879d/actionmailer/lib/action_mailer/base.rb#L353-L374)
  for reference.
- No mention of I18n, maybe could have at very brief section or paragraph/note
  somewhere that points to the [I18n guide on the
  matter](https://edgeguides.rubyonrails.org/i18n.html#translations-for-action-mailer-e-mail-subjects).

Co-authored-by: Ridhwana <[email protected]>
Co-authored-by: Petrik de Heus <[email protected]>
Co-authored-by: Harriet Oughton <[email protected]>
Co-authored-by: Dr Kim Foale <[email protected]>

Author: 5 people