Dynamically generate configuration docs using YARD (#968)

Dynamically generate configuration docs using YARD

.yardopts

@@ -0,0 +1 @@
+--plugin activesupport-concern

CHANGELOG.md

@@ -6,6 +6,10 @@
 
     *Joel Hawksley*
 
+* Add documentation for configuration options.
+
+    *Joel Hawksley*
+
 ## 2.34.0
 
 * Add the ability to enable ActiveSupport notifications (`!render.view_component` event) with `config.view_component.instrumentation_enabled`.

Gemfile.lock

@@ -219,6 +219,8 @@ GEM
     xpath (3.2.0)
       nokogiri (~> 1.8)
     yard (0.9.26)
+    yard-activesupport-concern (0.0.1)
+      yard (>= 0.8)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -241,6 +243,7 @@ DEPENDENCIES
   slim (~> 4.0)
   view_component!
   yard (~> 0.9.25)
+  yard-activesupport-concern
 
 BUNDLED WITH
    2.2.20

Rakefile

@@ -3,6 +3,7 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 require "yard"
+require "yard/mattr_accessor_handler"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -50,13 +51,18 @@ namespace :docs do
     registry = YARD::RegistryStore.new
     registry.load!(".yardoc")
 
-    instance_methods = registry.get("ViewComponent::Base").meths.select { |method| method.scope != :class }
-    instance_methods_to_document =
-      instance_methods.select do |method|
+    meths =
+      registry.
+      get("ViewComponent::Base").
+      meths.
+      select do |method|
         !method.tag(:private) &&
         method.path.include?("ViewComponent::Base") &&
         method.visibility == :public
-      end
+      end.sort_by { |method| method[:name] }
+
+    instance_methods_to_document = meths.select { |method| method.scope != :class }
+    class_methods_to_document = meths.select { |method| method.scope == :class }
 
     File.open("docs/api.md", "w") do |f|
       f.puts("---")
@@ -67,6 +73,31 @@ namespace :docs do
       f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
       f.puts
       f.puts("# API")
+
+      f.puts
+      f.puts("## Class methods")
+
+      class_methods_to_document.each do |method|
+        suffix =
+          if method.tag(:deprecated)
+            " (Deprecated)"
+          end
+
+        types = if method.tag(:return)&.types
+          " → [#{method.tag(:return).types.join(',')}]"
+        end
+
+        f.puts
+        f.puts("### #{method.sep}#{method.signature.gsub('def ', '')}#{types}#{suffix}")
+        f.puts
+        f.puts(method.docstring)
+
+        if method.tag(:deprecated)
+          f.puts
+          f.puts("_#{method.tag(:deprecated).text}_")
+        end
+      end
+
       f.puts
       f.puts("## Instance methods")
 
@@ -90,6 +121,35 @@ namespace :docs do
           f.puts("_#{method.tag(:deprecated).text}_")
         end
       end
+
+      f.puts
+      f.puts("## Configuration")
+
+      registry.
+        get("ViewComponent::Base").
+        meths.
+        select { |method| method[:mattr_accessor] }.
+        sort_by { |method| method[:name] }.
+        each do |method|
+
+        suffix =
+          if method.tag(:deprecated)
+            " (Deprecated)"
+          end
+
+        f.puts
+        f.puts("### #{method.sep}#{method.name}#{suffix}")
+
+        if method.docstring.length > 0
+          f.puts
+          f.puts(method.docstring)
+        end
+
+        if method.tag(:deprecated)
+          f.puts
+          f.puts("_#{method.tag(:deprecated).text}_")
+        end
+      end
     end
   end
 end

docs/api.md

@@ -7,6 +7,20 @@ title: API
 
 # API
 
+## Class methods
+
+### .with_collection(collection, **args)
+
+Render a component for each element in a collection ([documentation](/guide/collections)):
+
+    render(ProductsComponent.with_collection(@products, foo: :bar))
+
+### .with_collection_parameter(parameter)
+
+Set the parameter name used when rendering elements of a collection ([documentation](/guide/collections)):
+
+    with_collection_parameter :item
+
 ## Instance methods
 
 ### #_output_postamble → [String]
@@ -21,11 +35,7 @@ Called before rendering the component. Override to perform operations that depen
 
 Called after rendering the component.
 
-_Use `before_render` instead. Will be removed in v3.0.0._
-
-### #render? → [Boolean]
-
-Override to determine whether the ViewComponent should render.
+_Use `#before_render` instead. Will be removed in v3.0.0._
 
 ### #controller → [ActionController::Base]
 
@@ -35,10 +45,71 @@ The current controller. Use sparingly as doing so introduces coupling that inhib
 
 A proxy through which to access helpers. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
 
-### #with_variant(variant) → [self]
+### #render? → [Boolean]
 
-Use the provided variant instead of the one determined by the current request.
+Override to determine whether the ViewComponent should render.
 
 ### #request → [ActionDispatch::Request]
 
 The current request. Use sparingly as doing so introduces coupling that inhibits encapsulation & reuse, often making testing difficult.
+
+### #with_variant(variant) → [self]
+
+Use the provided variant instead of the one determined by the current request.
+
+## Configuration
+
+### #default_preview_layout
+
+Set a custom default layout used for preview index and individual previews:
+
+    config.view_component.default_preview_layout = "component_preview"
+
+### #preview_controller
+
+Set the controller used for previewing components:
+
+    config.view_component.preview_controller = "MyPreviewController"
+
+Defaults to `ViewComponentsController`.
+
+### #preview_path (Deprecated)
+
+_Use `preview_paths` instead. Will be removed in v3.0.0._
+
+### #preview_paths
+
+Set the location of component previews:
+
+    config.view_component.preview_paths << "#{Rails.root}/lib/component_previews"
+
+### #preview_route
+
+Set the entry route for component previews:
+
+    config.view_component.preview_route = "/previews"
+
+Defaults to `/rails/view_components` when `show_previews` is enabled.
+
+### #render_monkey_patch_enabled
+
+Set if render monkey patches should be included or not in Rails <6.1:
+
+    config.view_component.render_monkey_patch_enabled = false
+
+### #show_previews
+
+Enable or disable component previews:
+
+    config.view_component.show_previews = true
+
+Defaults to `true` in development.
+
+### #test_controller
+
+Set the controller used for testing components:
+
+    config.view_component.test_controller = "MyTestController"
+
+Defaults to ApplicationController. Can also be configured on a per-test
+basis using `with_controller_class`.