Document action_mailer.file_settings [ci-skip]

I was reading the Action Mailer guide and noticed the settings and
defaults for the `:file` delivery method were poorly documented. These
docs were originally added back in rails#13728. rails#44422 added links to the
relevant sections of the Configuration guide, but did not link
`config.action_mailer.file_settings` because the Configuration guide is
actually missing that section.

I added a short section to the Configuration guide for
`config.action_mailer.file_settings` and linked to it from the Action
Mailer guide, following the style of the other delivery methods. Like
other delivery methods, the relevant options for `file_settings` come
from the allowed options of the `Mail::FileDelivery` class in the mail
gem.

Here's where Rails sets up this delivery method with the default
location:
https://github.com/rails/rails/blob/9064735ec5cd3c679f8ffabc42532dd85223af58/actionmailer/lib/action_mailer/delivery_methods.rb#L30-L31

And here's where the mail gem uses the options:
https://github.com/mikel/mail/blob/10a4443b9d4ffa71b9ad643ad86cc23ccc99f0f3/lib/mail/network/delivery_methods/file_delivery.rb#L21

Author: mkasberg

guides/source/action_mailer_basics.md

@@ -854,7 +854,7 @@ files (environment.rb, production.rb, etc...)
 |`smtp_settings`|Allows detailed configuration for `:smtp` delivery method:<ul><li>`:address` - Allows you to use a remote mail server. Just change it from its default `"localhost"` setting.</li><li>`:port` - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li>`:domain` - If you need to specify a HELO domain, you can do it here.</li><li>`:user_name` - If your mail server requires authentication, set the username in this setting.</li><li>`:password` - If your mail server requires authentication, set the password in this setting.</li><li>`:authentication` - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of `:plain` (will send the password in the clear), `:login` (will send password Base64 encoded) or `:cram_md5` (combines a Challenge/Response mechanism to exchange information and a cryptographic Message Digest 5 algorithm to hash important information)</li><li>`:enable_starttls` - Use STARTTLS when connecting to your SMTP server and fail if unsupported. Defaults to `false`.</li><li>`:enable_starttls_auto` - Detects if STARTTLS is enabled in your SMTP server and starts to use it. Defaults to `true`.</li><li>`:openssl_verify_mode` - When using TLS, you can set how OpenSSL checks the certificate. This is really useful if you need to validate a self-signed and/or a wildcard certificate. You can use the name of an OpenSSL verify constant ('none' or 'peer') or directly the constant (`OpenSSL::SSL::VERIFY_NONE` or `OpenSSL::SSL::VERIFY_PEER`).</li><li>`:ssl/:tls` - Enables the SMTP connection to use SMTP/TLS (SMTPS: SMTP over direct TLS connection)</li><li>`:open_timeout` - Number of seconds to wait while attempting to open a connection.</li><li>`:read_timeout` - Number of seconds to wait until timing-out a read(2) call.</li></ul>|
 |`sendmail_settings`|Allows you to override options for the `:sendmail` delivery method.<ul><li>`:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.</li><li>`:arguments` - The command line arguments to be passed to sendmail. Defaults to `["-i"]`.</li></ul>|
 |`raise_delivery_errors`|Whether or not errors should be raised if the email fails to be delivered. This only works if the external email server is configured for immediate delivery. Defaults to `true`.|
-|`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured by using [`config.action_mailer.smtp_settings`][].</li><li>`:sendmail`, can be configured by using [`config.action_mailer.sendmail_settings`][].</li><li>`:file`: save emails to files; can be configured by using `config.action_mailer.file_settings`.</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
+|`delivery_method`|Defines a delivery method. Possible values are:<ul><li>`:smtp` (default), can be configured with [`config.action_mailer.smtp_settings`][].</li><li>`:sendmail`, can be configured with [`config.action_mailer.sendmail_settings`][].</li><li>`:file`: save emails to files; can be configured with [`config.action_mailer.file_settings`][].</li><li>`:test`: save emails to `ActionMailer::Base.deliveries` array.</li></ul>See [API docs](https://api.rubyonrails.org/classes/ActionMailer/Base.html) for more info.|
 |`perform_deliveries`|Determines whether deliveries are actually carried out when the `deliver` method is invoked on the Mail message. By default they are, but this can be turned off to help functional testing. If this value is `false`, `deliveries` array will not be populated even if `delivery_method` is `:test`.|
 |`deliveries`|Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.|
 |`delivery_job`|The job class used with `deliver_later`. Defaults to `ActionMailer::MailDeliveryJob`.|
@@ -867,6 +867,7 @@ our Configuring Rails Applications guide.
 
 [`config.action_mailer.sendmail_settings`]: configuring.html#config-action-mailer-sendmail-settings
 [`config.action_mailer.smtp_settings`]: configuring.html#config-action-mailer-smtp-settings
+[`config.action_mailer.file_settings`]: configuring.html#config-action-mailer-file-settings
 
 ### Example Action Mailer Configuration
 

guides/source/configuring.md

@@ -2285,11 +2285,18 @@ The default value depends on the `config.load_defaults` target version:
 
 #### `config.action_mailer.sendmail_settings`
 
-Allows detailed configuration for the `sendmail` delivery method. It accepts a hash of options, which can include any of these options:
+Allows detailed configuration for the `:sendmail` delivery method. It accepts a hash of options, which can include any of these options:
 
 * `:location` - The location of the sendmail executable. Defaults to `/usr/sbin/sendmail`.
 * `:arguments` - The command line arguments. Defaults to `%w[ -i ]`.
 
+#### `config.action_mailer.file_settings`
+
+Configures the `:file` delivery method. It accepts a hash of options, which can include:
+
+* `:location` - The location where files are saved. Defaults to `"#{Rails.root}/tmp/mails"`.
+* `:extension` - The file extension. Defaults to the empty string.
+
 #### `config.action_mailer.raise_delivery_errors`
 
 Specifies whether to raise an error if email delivery cannot be completed. It defaults to `true`.