Disable mailers parsing by default, add config option to enable

docs/alpha/01_usage.md

@@ -24,7 +24,7 @@ Add Lookbook to the `development` group in your Gemfile:
 
 ```rb
 group :development do
-  gem "lookbook", "~> 3.0.0.alpha.1"
+  gem "lookbook", "~> 3.0.0.alpha.2"
   gem "listen" # Required for 'live' UI updates when file changes are detected
 end
 ```
@@ -57,7 +57,7 @@ gem "actioncable" # Remove this!
 Lastly **update the Lookbook version** in your `Gemfile`:
 
 ```rb
-gem "lookbook", "~> 3.0.0.alpha.1"
+gem "lookbook", "~> 3.0.0.alpha.2"
 ```
 
 Run `bundle update lookbook` to update to the latest Lookbook alpha release and then start your server in the usual way.

docs/alpha/02_new_features.md

@@ -4,63 +4,6 @@
 
 Below are details of some of the main new features that have been implemented so far in Lookbook v3. Give them a try and let us know what you think!
 
-## 🆕 ActionMailer previews
-
-> ⚠️ ActionMailer preview support is still very much at an experimental stage. Any feedback and/or suggestions on this feature would be very welcome!
-
-[➡️ Demo example](https://v3-demo-app.lookbook.build/lookbook/previews/user_mailer/welcome)
-
-ActionMailer previews are supported out-of-the-box in v3, with no changes required to the regular [ActionMailer preview format](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails):
-
-```rb
-class UserMailerPreview < ActionMailer::Preview
-  def welcome_email
-    UserMailer.with(name: "Bob").welcome_email
-  end
-end
-```
-
-Any existing mailer previews in your should automatically appear in the Lookbook UI.
-
-Mailer previews can be located in the standard Rails mailer preview directory (`test/mailers/previews`) or if you prefer to keep things altogether they can be added into the main Lookbook previews directory.
-
-All the usual Lookbook [tags/annotations](https://lookbook.build/guide/tags) (apart from `@!group` tags) can be used in ActionMailer previews in exactly the same way as in component previews:
-
-```rb
-class UserMailerPreview < ActionMailer::Preview
-  # @label New user welcome
-  def welcome_email
-    UserMailer.with(name: "Bob").welcome_email
-  end
-
-  # This email is still WIP and not ready for use.
-  # @hidden
-  def experimental_email
-    UserMailer.with(name: "Bob").experimental_email
-  end
-end
-```
-
-[Dynamic params](https://lookbook.build/guide/previews/params) work in the same way as component previews, as long as the param values are passed to the email template as instance variables:
-
-```rb
-class UserMailer < ApplicationMailer
-  def welcome
-    @name = params[:name]
-    mail(to: "[email protected]", subject: "Welcome")
-  end
-end
-```
-
-```rb
-class UserMailerPreview < ActionMailer::Preview
-  # @param name
-  def welcome_email(name: "Bob")
-    UserMailer.with(name: name).welcome_email
-  end
-end
-```
-
 ## 🆕 Preview overview pages
 
 Preview overview pages are generated for each preview class and shown when clicking on the preview name in the navigation.
@@ -202,10 +145,76 @@ label: Feedback
 In the example above the parent folder name would be displayed as `Feedback` instead of `Alerts` in the navigation.
 
 
+## 🆕 ActionMailer previews
 
+> ⚠️ ActionMailer preview support is still very much at an experimental stage. Any feedback and/or suggestions on this feature would be very welcome!
 
+[➡️ Demo example](https://v3-demo-app.lookbook.build/lookbook/previews/user_mailer/welcome)
+
+### Enabling ActionMailer preview support
+
+Lookbook mailer previews are an experimental feature and must be enabled using the `experimental_features` config option:
+
+```rb
+config.lookbook.experimental_features << :mailer_previews
+```
+
+### Usage
+
+The intention is to support standard ActionMailer previews are out-of-the-box in Lookbook v3, with no changes required to the regular [ActionMailer preview format](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails):
+
+```rb
+class UserMailerPreview < ActionMailer::Preview
+  def welcome_email
+    UserMailer.with(name: "Bob").welcome_email
+  end
+end
+```
+
+Any existing mailer previews in your should automatically appear in the Lookbook UI.
+
+Mailer previews can be located in the standard Rails mailer preview directory (`test/mailers/previews`) or if you prefer to keep things altogether they can be added into the main Lookbook previews directory.
+
+All the usual Lookbook [tags/annotations](https://lookbook.build/guide/tags) (apart from `@!group` tags) can be used in ActionMailer previews in exactly the same way as in component previews:
+
+```rb
+class UserMailerPreview < ActionMailer::Preview
+  # @label New user welcome
+  def welcome_email
+    UserMailer.with(name: "Bob").welcome_email
+  end
+
+  # This email is still WIP and not ready for use.
+  # @hidden
+  def experimental_email
+    UserMailer.with(name: "Bob").experimental_email
+  end
+end
+```
+
+[Dynamic params](https://lookbook.build/guide/previews/params) work in the same way as component previews, as long as the param values are passed to the email template as instance variables:
+
+```rb
+class UserMailer < ApplicationMailer
+  def welcome
+    @name = params[:name]
+    mail(to: "[email protected]", subject: "Welcome")
+  end
+end
+```
+
+```rb
+class UserMailerPreview < ActionMailer::Preview
+  # @param name
+  def welcome_email(name: "Bob")
+    UserMailer.with(name: name).welcome_email
+  end
+end
+```
 
+## Lots more!
 
+More docs/info to come.
 
 
 

lib/lookbook/config.rb

@@ -58,6 +58,8 @@ def defaults
           reload_on_change: Rails.env.development?,
           mount_path: "/lookbook",
 
+          experimental_features: [],
+
           enabled: Rails.env.development? || Rails.env.test?
         })
       end

lib/lookbook/engine.rb

@@ -22,6 +22,12 @@ class Engine < Rails::Engine
     end
 
     config.after_initialize do
+      if Lookbook.config.experimental_features.any?
+        warn(%(
+          The following experimental features are enabled: #{Lookbook.config.experimental_features.join(", ")}
+          Please note these may change or be removed at any time.).strip_heredoc)
+      end
+
       if Engine.enabled?
         start
       else

lib/lookbook/previews/previews.rb

@@ -65,7 +65,7 @@ def preview_class?(klass)
 
       def preview_paths
         @preview_paths ||= begin
-          action_mailer_paths = if Rails.application.config.respond_to?(:action_mailer)
+          action_mailer_paths = if mailer_previews_enabled? && Rails.application.config.respond_to?(:action_mailer)
             Rails.application.config.action_mailer.preview_paths
           end
           paths = [Lookbook.config.preview_paths, action_mailer_paths].compact.flatten
@@ -122,6 +122,10 @@ def statuses
         end
       end
 
+      def mailer_previews_enabled?
+        Lookbook.config.experimental_features.include?(:mailer_previews)
+      end
+
       private
 
       def clear_cache

lib/lookbook/previews/previews_parser.rb

@@ -33,6 +33,10 @@ def parse(paths = @preview_paths, &callback)
           nil
         end
 
+        unless Previews.mailer_previews_enabled?
+          preview_entities = preview_entities.filter { !_1.mailer_preview? }
+        end
+
         callback.call(preview_entities.compact)
       end
     end

test/demo/config/application.rb

@@ -37,6 +37,8 @@
     }
   }
 
+  config.lookbook.experimental_features << :mailer_previews
+
   # Pages config
 
   config.lookbook.page_paths << "#{root}/lookbook/docs"