Improve ActionText::FixtureSet documentation (#41062)

* Improve ActionText::FixtureSet documentation

Support for Action Text attachments in fixtures was added by [76b33aa][] and
released as part of [6.1.1][], but has not yet been documented.

This commit documents the `ActionText::FixtureSet` for the API
documentation, and mentions it in the Rails Guides pages.

[76b33aa]: 76b33aa3d1
[6.1.1]: https://github.com/rails/rails/releases/tag/v6.1.1

* Fix indention of comments

Co-authored-by: David Heinemeier Hansson <david@loudthinking.com>

actiontext/lib/action_text/fixture_set.rb

@@ -1,7 +1,56 @@
 # frozen_string_literal: true
 
 module ActionText
+  # Fixtures are a way of organizing data that you want to test against; in
+  # short, sample data.
+  #
+  # To learn more about fixtures, read the
+  # {ActiveRecord::FixtureSet}[rdoc-ref:ActiveRecord::FixtureSet] documentation.
+  #
+  # === YAML
+  #
+  # Like other Active Record-backed models, ActionText::RichText records inherit
+  # from ActiveRecord::Base instances and therefore can be populated by
+  # fixtures.
+  #
+  # Consider a hypothetical <tt>Article</tt> model class, its related fixture
+  # data, as well as fixture data for related ActionText::RichText records:
+  #
+  #   # app/models/article.rb
+  #   class Article < ApplicationRecord
+  #     has_rich_text :content
+  #   end
+  #
+  #   # tests/fixtures/articles.yml
+  #   first:
+  #     title: An Article
+  #
+  #   # tests/fixtures/action_text/rich_texts.yml
+  #   first_content:
+  #     record: first (Article)
+  #     name: content
+  #     body: <div>Hello, world.</div>
+  #
+  # When processed, Active Record will insert database records for each fixture
+  # entry and will ensure the Action Text relationship is intact.
   class FixtureSet
+    # Fixtures support Action Text attachments as part of their <tt>body</tt>
+    # HTML.
+    #
+    # === Examples
+    #
+    # For example, consider a second <tt>Article</tt> record that mentions the
+    # first as part of its <tt>content</tt> HTML:
+    #
+    #   # tests/fixtures/articles.yml
+    #   second:
+    #     title: Another Article
+    #
+    #   # tests/fixtures/action_text/rich_texts.yml
+    #   second_content:
+    #     record: second (Article)
+    #     name: content
+    #     body: <div>Hello, <%= ActionText::FixtureSet.attachment("artcles", :first) %></div>
     def self.attachment(fixture_set_name, label, column_type: :integer)
       signed_global_id = ActiveRecord::FixtureSet.signed_global_id fixture_set_name, label,
         column_type: column_type, for: ActionText::Attachable::LOCATOR_NAME

guides/source/testing.md

@@ -640,11 +640,18 @@ about:
 # fixtures/articles.yml
 first:
   title: Welcome to Rails!
-  body: Hello world!
   category: about
 ```
 
-Notice the `category` key of the `first` article found in `fixtures/articles.yml` has a value of `about`. This tells Rails to load the category `about` found in `fixtures/categories.yml`.
+```yaml
+# fixtures/action_text/rich_texts.yml
+first_content:
+  record: first (Article)
+  name: content
+  body: <div>Hello, from <strong>a fixture</strong></div>
+```
+
+Notice the `category` key of the `first` Article found in `fixtures/articles.yml` has a value of `about`, and that the `record` key of the `first_content` entry found in `fixtures/action_text/rich_texts.yml` has a value of `first (Article)`. This hints to Active Record to load the Category `about` found in `fixtures/categories.yml` for the former, and Action Text to load the Article `first` found in `fixtures/articles.yml` for the latter.
 
 NOTE: For associations to reference one another by name, you can use the fixture name instead of specifying the `id:` attribute on the associated fixtures. Rails will auto assign a primary key to be consistent between runs. For more information on this association behavior please read the [Fixtures API documentation](https://api.rubyonrails.org/classes/ActiveRecord/FixtureSet.html).