lookbook 0.7.2 → 0.8.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6df32e43d6fbb0a7b88e0db9bbb4bd9562f3528f3a7160463d078daf262954f3
-  data.tar.gz: cfbd08c5a4d06a56ef8bd9016139e3d04a4195e2590d5be741e1c238ce390744
+  metadata.gz: aa9a6048a7c6da30fcf5fe7c42a0a41365c3964da88d1d639a640c1acdd97a95
+  data.tar.gz: dbbf4e04289ccadde4f37453123aabc70d982104b6933b3e139b0c65ea2a68f4
 SHA512:
-  metadata.gz: bd42877713e33dc0ad3d1bf4fddc1ab561171d01417f6b415ceda15abeeba45996c9e0478afb02117363a1686b063daf1e283ff0f84c6d0b591c59c50e0ba744
-  data.tar.gz: e12acc1799810736e3f5bad6e3d096f7c1f68ddb0de5b0d1aa0324f1b7b0bd707d733750c5ed8a56cb3ab87d921036cd7b340927971186f98bbf5a402d41acf0
+  metadata.gz: a9eea08255c6263b84d6212d88d4a08ac425377eb1b0f42e4c5e626e04e1281e711c3ba41df98b550e3777b4e292824884ecd5e05b733db97126ccb6ba4cd100
+  data.tar.gz: 8b48c299198427e2e957eb6c3dcccf6ae1544a921ef5ae4ba37fad558dd0274a1f864e9b8a37fb5b76a49c275f74f5a73e3363a8c6c4d4092a380639b99798e8

data/README.md

@@ -13,7 +13,7 @@
 ---
 
 <div align="center">
-<a href="#installing">Installing</a> • <a href="#previews">Previews</a>  • <a href="#pages">Pages</a> • <a href="#config">Configuration</a> 
+<a href="#installing">Installing</a> • <a href="#previews">Previews</a>  • <a href="#pages">Pages</a> • <a href="#deployment">Deployment</a> • <a href="#config">Config</a> 
 </div>
 
 ---
@@ -72,13 +72,6 @@ The `at` property determines the root URL that the Lookbook UI will be served at
 
 Then you can start your app as normal and navigate to `http://localhost:3000/lookbook` (or whatever mount path you specified) to view your component previews in the Lookbook UI.
 
-#### Mounting in Production
-
-If you would like to expose the Lookbook UI in production as well as in development
-
-1. Remove the `if Rails.env.development?` condition from around the mount statement in `routes.rb`
-2. Add `config.view_component.show_previews = true` to `config/environments/production.rb`
-
 
 <h2 id="previews">Previews</h2>
 
@@ -687,6 +680,73 @@ Default: `pages`
 config.lookbook.page_route = `docs`
 ```
 
+<h2 id="deployment">Deploying in Production</h2>
+
+Lookbook is intended to be a tool for aiding the ViewComponent development process, and so is usually restricted to running only when the app is in `development` mode.
+
+However, it is possible to run Lookbook in a production environment if you wish.
+
+### Differences between development and production
+
+By default, Lookbook will behave a little differently in production than it does in development:
+
+1. Watching files for changes is disabled
+2. Parsing preview files for annotations does **not** happen at runtime. Instead the preview files must be pre-parsed via a Rake task before starting the app (much like asset precompilation).
+
+### Pre-parsing preview files
+
+Run the following command to pre-parse the preview files annotations:
+
+```
+rake lookbook:previews:preparse
+```
+
+If you wish to run this as part of your existing assets precompilation step, you can add the following into your app's `Rakefile`:
+
+```ruby
+Rake::Task['assets:precompile'].enhance do
+  Rake::Task["lookbook:previews:preparse"].invoke
+end
+```
+
+The pre-parsing of preview files will then take place every time `rake assets:precompile` is called and so will not need to be run separately.
+
+### Configuration changes for production
+
+You will also need to make sure that the following configuration changes have been made when deploying to production:
+
+1. Make sure ViewComponent is [configured to show previews in production](https://viewcomponent.org/api.html#show_previews) (by default it is disabled when not in development):
+
+```ruby
+# config/environments/production.rb
+config.view_component.show_previews = true
+```
+
+2. Remove any environment checking from around the Lookbook mounting declaration (if added as per install instructions):
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # if Rails.env.development? <- remove
+    mount Lookbook::Engine, at: "/lookbook"
+  # end
+end
+```
+
+### Overriding production default behaviours
+
+If for some reason you wish to enable file watching or runtime preview annotation parsing in production, you can always override the default behaviour using thie following config options:
+
+```ruby
+# config/environments/production.rb
+
+# enable file-change listening
+config.lookbook.listen = true 
+
+# enable runtime preview parsing
+config.lookbook.runtime_parsing = true 
+```
+
 <h2 id="config">General Configuration</h2>
 
 Lookbook will use the ViewComponent [configuration](https://viewcomponent.org/api.html#configuration) for your project to find and render your previews so you generally you won't need to configure much else separately.

data/app/controllers/lookbook/previews_controller.rb

@@ -145,7 +145,6 @@ module Lookbook
     def preview_controller
       return @preview_controller if @preview_controller.present?
       controller_class = Lookbook.config.preview_controller.constantize
-      controller_class.class_eval { include Lookbook::PreviewController }
       controller = controller_class.new
       controller.request = request
       controller.response = response

data/app/views/lookbook/previews/panels/_params.html.erb

@@ -1,4 +1,4 @@
-<div class="bg-gray-50 h-full">
+<div class="bg-gray-50 h-full overflow-auto">
   <% if @example.type == :group %>
     <div class="p-4 prose prose-sm">
       <em class='opacity-50'>Params are not yet supported for grouped examples.</em>

data/config/routes.rb

@@ -1,6 +1,6 @@
 Lookbook::Engine.routes.draw do
   if Lookbook.config.auto_refresh
-    mount Lookbook::Engine.websocket => Lookbook.config.cable.mount_path
+    mount Lookbook::Engine.websocket => Lookbook.config.cable_mount_path
   end
 
   root to: "application#index", as: :home

data/lib/lookbook/engine.rb

@@ -10,7 +10,7 @@ module Lookbook
     end
 
     def logger
-      @logger ||= config.debug == true ? Rails.logger : Lookbook::NullLogger.new
+      @logger ||= Rails.logger
     end
 
     def version
@@ -49,15 +49,17 @@ module Lookbook
       options.preview_srcdoc = false if options.preview_srcdoc.nil?
       options.preview_display_params ||= {}.with_indifferent_access
 
+      options.listen = Rails.env.development? if options.listen.nil?
       options.listen_paths = options.listen_paths.map(&:to_s)
       options.listen_paths += options.preview_paths
       options.listen_paths << (vc_options.view_component_path || Rails.root.join("app/components"))
       options.listen_paths.filter! { |path| Dir.exist? path }
 
-      options.cable = ActionCable::Server::Configuration.new
-      options.cable.cable = {adapter: "async"}.with_indifferent_access
-      options.cable.mount_path ||= "/lookbook-cable"
-      options.cable.connection_class = -> { Lookbook::Connection }
+      options.cable_mount_path ||= "/lookbook-cable"
+      options.cable_logger ||= Rails.logger
+
+      options.runtime_parsing = !Rails.env.production? if options.runtime_parsing.nil?
+      options.parser_registry_path ||= Rails.root.join("tmp/storage/.yardoc")
 
       options.experimental_features = false unless options.experimental_features.present?
     end
@@ -73,41 +75,48 @@ module Lookbook
       )
     end
 
-    initializer "lookbook.logging" do
-      if config.lookbook.debug == true
-        config.lookbook.cable.logger ||= Rails.logger
-      else
-        config.lookbook.cable.logger = Lookbook::NullLogger.new
-      end
-    end
-
     config.after_initialize do
-      @preview_listener = Listen.to(*config.lookbook.listen_paths, only: /\.(rb|html.*)$/) do |modified, added, removed|
-        begin
-          parser.parse
-        rescue
-        end
-        Lookbook::Preview.clear_cache
-        Lookbook::Engine.websocket&.broadcast("reload", {
-          modified: modified,
-          removed: removed,
-          added: added
-        })
-      end
-      @preview_listener.start
-
-      if Lookbook::Features.enabled?(:pages)
-        @page_listener = Listen.to(*config.lookbook.page_paths.filter { |dir| Dir.exist? dir }, only: /\.(html.*|md.*)$/) do |modified, added, removed|
+      preview_controller = Lookbook.config.preview_controller.constantize
+      preview_controller.class_eval { include Lookbook::PreviewController }
+
+      if config.lookbook.listen
+        @preview_listener = Listen.to(*config.lookbook.listen_paths, only: /\.(rb|html.*)$/) do |modified, added, removed|
+          begin
+            parser.parse
+          rescue
+          end
+          Lookbook::Preview.clear_cache
           Lookbook::Engine.websocket&.broadcast("reload", {
             modified: modified,
             removed: removed,
             added: added
           })
         end
-        @page_listener.start
-      end
+        @preview_listener.start
+
+        if Lookbook::Features.enabled?(:pages)
+          @page_listener = Listen.to(*config.lookbook.page_paths.filter { |dir| Dir.exist? dir }, only: /\.(html.*|md.*)$/) do |modified, added, removed|
+            Lookbook::Engine.websocket&.broadcast("reload", {
+              modified: modified,
+              removed: removed,
+              added: added
+            })
+          end
+          @page_listener.start
+        end
 
-      parser.parse
+        if config.lookbook.runtime_parsing
+          parser.parse
+        else
+          unless File.exist?(config.lookbook.parser_registry_path)
+            Lookbook.logger.warn "
+              Runtime parsing is disabled but no registry file has been found.
+              Did you run `rake lookbook:preparse` before starting the app?
+              Expected to find registry file at #{config.lookbook.parser_registry_path}
+            "
+          end
+        end
+      end
     end
 
     at_exit do
@@ -118,18 +127,24 @@ module Lookbook
     class << self
       def websocket
         if config.lookbook.auto_refresh
+          cable = ActionCable::Server::Configuration.new
+          cable.cable = {adapter: "async"}.with_indifferent_access
+          cable.mount_path = config.lookbook.cable_mount_path
+          cable.connection_class = -> { Lookbook::Connection }
+          cable.logger = config.lookbook.cable_logger
+
           @websocket ||= if Rails.version.to_f >= 6.0
-            ActionCable::Server::Base.new(config: config.lookbook.cable)
+            ActionCable::Server::Base.new(config: cable)
           else
             websocket ||= ActionCable::Server::Base.new
-            websocket.config = config.lookbook.cable
+            websocket.config = cable
             websocket
           end
         end
       end
 
       def websocket_mount_path
-        "#{mounted_path}#{config.lookbook.cable.mount_path}" if websocket
+        "#{mounted_path}#{config.lookbook.cable_mount_path}" if websocket
       end
 
       def mounted_path
@@ -137,7 +152,7 @@ module Lookbook
       end
 
       def parser
-        @parser ||= Lookbook::Parser.new(config.lookbook.preview_paths)
+        @parser ||= Lookbook::Parser.new(config.lookbook.preview_paths, config.lookbook.parser_registry_path)
       end
     end
   end

data/lib/lookbook/parser.rb

@@ -2,27 +2,31 @@ require "yard"
 
 module Lookbook
   class Parser
-    YARDOC_FILE_PATH = Rails.root.join("tmp/storage/.yardoc").to_s
-
-    def initialize(paths)
+    attr_reader :registry_path
+    def initialize(paths, registry_path)
       @paths = paths.map { |p| "#{p}/**/*preview.rb" }
-      YARD::Registry.yardoc_file = YARDOC_FILE_PATH
+      @registry_path = registry_path.to_s
+      YARD::Registry.yardoc_file = registry_path
     end
 
     def parse
       YARD::Registry.clear
       YARD::Registry.lock_for_writing do
         YARD.parse(@paths)
-        YARD::Registry.save(false, YARDOC_FILE_PATH)
+        YARD::Registry.save(false, registry_path)
       end
     end
 
     def get_code_object(path)
       registry = YARD::RegistryStore.new
-      registry.load!(YARDOC_FILE_PATH)
+      registry.load!(registry_path)
       registry.get(path)
     end
 
+    # def yardoc_file_path
+    #   Rails&.root ? Rails.root.join(YARDOC_FILE_PATH) : YARDOC_FILE_PATH
+    # end
+
     class << self
       def define_tags
         YARD::Tags::Library.define_tag("Hidden status", :hidden)

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "0.7.2"
+  VERSION = "0.8.0.beta.0"
 end

data/lib/lookbook.rb

@@ -20,7 +20,6 @@ module Lookbook
   autoload :PreviewExample, "lookbook/preview_example"
   autoload :PreviewGroup, "lookbook/preview_group"
   autoload :CodeInspector, "lookbook/code_inspector"
-  autoload :NullLogger, "lookbook/null_logger"
   autoload :CodeFormatter, "lookbook/code_formatter"
   autoload :Markdown, "lookbook/markdown"
 

data/lib/tasks/lookbook_tasks.rake

@@ -1,6 +1,15 @@
 require_relative "../lookbook"
 
 namespace :lookbook do
+
+  namespace :previews do
+    desc "Preparse the previews"
+    task :preparse do
+      Lookbook::Engine.parser.parse
+      puts "Lookbook preview parsing complete"
+    end
+  end
+
   namespace :release do
     desc "Bump the Lookbook engine version number"
     task :bump_version, [:version] do |t, args|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lookbook
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0.beta.0
 platform: ruby
 authors:
 - Mark Perkins
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-05 00:00:00.000000000 Z
+date: 2022-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -290,7 +290,6 @@ files:
 - lib/lookbook/features.rb
 - lib/lookbook/lang.rb
 - lib/lookbook/markdown.rb
-- lib/lookbook/null_logger.rb
 - lib/lookbook/page.rb
 - lib/lookbook/page_collection.rb
 - lib/lookbook/params.rb
@@ -325,9 +324,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.2.22
 signing_key:

data/lib/lookbook/null_logger.rb

@@ -1,47 +0,0 @@
-module Lookbook
-  class NullLogger
-    def unknown(*)
-      nil
-    end
-
-    def fatal(*)
-      nil
-    end
-
-    def fatal?
-      false
-    end
-
-    def error(*)
-      nil
-    end
-
-    def error?
-      false
-    end
-
-    def warn(*)
-      nil
-    end
-
-    def warn?
-      false
-    end
-
-    def info(*)
-      nil
-    end
-
-    def info?
-      false
-    end
-
-    def debug(*)
-      nil
-    end
-
-    def debug?
-      false
-    end
-  end
-end