lookbook 2.0.0.beta.2 → 2.0.0.beta.4

data/lib/lookbook/entities/concerns/locatable_entity.rb

@@ -1,40 +1,77 @@
 module Lookbook
-  # @api private
   module LocatableEntity
     extend ActiveSupport::Concern
 
     included do
-      attr_reader :file_path, :base_directories
-
+      # @!group Paths
+
+      # Full path to the entity file
+      #
+      # @return [Pathname] File patj
+      attr_reader :file_path
+
+      # @api private
+      attr_reader :base_directories
+
+      # Name of the entity file.
+      #
+      # Includes file extension unless the `strip_ext` argument is `true`.
+      #
+      # @param strip_ext [Boolean] Whether or not to remove the file extension
+      # @return [String] File name
       def file_name(strip_ext = false)
         basename = file_pathname.basename
         (strip_ext ? basename.to_s.split(".").first : basename).to_s
       end
 
-      def file_name_base
-        @_file_name_slug ||= file_name(true).gsub(/(_component_preview|component_preview|preview)$/, "")
-      end
-
+      # Extension of the entity file.
+      #
+      # @return [String] File extension
       def file_extension
         @_file_extension ||= file_pathname.extname
       end
 
+      # Full directory path for the entity file.
+      #
+      # @return [Pathname] Directory path
       def directory_path
         @_directory_path ||= Pathname(file_pathname.dirname)
       end
 
+      # Relative path to the entity file.
+      #
+      # Returned path is relative to the appropriate base directory
+      # (i.e. the preview directory for previews).
+      #
+      # @return [Pathname] Relative file path
       def relative_file_path
         @_relative_file_path ||= file_pathname.relative_path_from(base_directory)
       end
 
+      # Relative directory path for the entity file.
+      #
+      # Returned path is relative to the appropriate base directory
+      # (i.e. the preview directory for previews).
+      #
+      # @return [Pathname] Relative directory path
       def relative_directory_path
         @_relative_directory_path ||= directory_path.relative_path_from(base_directory)
       end
 
+      # Time that the entity file was last modified
+      #
+      # @return [Time] Time last modified
       def last_modified
         @_last_modified ||= File.mtime(file_path)
       end
 
+      # 'Virtual' path to the entity.
+      #
+      # Determines where the entity is located in heirarchical trees.
+      # Can be altered using the `@logical_path` tag.
+      #
+      # @api private
+      # @return [String] The logical path
       def logical_path
         return @_logical_path if @_logical_path
 
@@ -42,6 +79,13 @@ module Lookbook
         @_logical_path ||= PathUtils.to_path(directory, file_name_base)
       end
 
+      # @!endgroup
+
+      # @api private
+      def file_name_base
+        @_file_name_slug ||= file_name(true)
+      end
+
       alias_method :full_path, :file_path
       alias_method :rel_path, :relative_file_path
       alias_method :dir_path, :directory_path

data/lib/lookbook/entities/concerns/navigable_entity.rb

@@ -1,17 +1,27 @@
 module Lookbook
-  # @api private
   module NavigableEntity
     extend ActiveSupport::Concern
 
     included do
+      # @!group Visibility
+
+      # Whether or not the entity is hidden (i.e. hidden from navigation)
+      #
+      # @return [Boolean] true if hidden
       def hidden?
         fetch_config(:hidden, false)
       end
 
+      # Whether or not the entity is visible (i.e. present in navigation)
+      #
+      # @return [Boolean] true if visible
       def visible?
         !hidden?
       end
 
+      # @!endgroup
+
+      # @api private
       def priority
         return @_priority if @_priority
 
@@ -24,14 +34,17 @@ module Lookbook
         @_priority ||= pos.to_i
       end
 
+      # @api private
       def depth
         lookup_path.split("/").size
       end
 
+      # @api private
       def default_priority
         @default_priority || 10000
       end
 
+      # @api private
       def <=>(other)
         if respond_to?(:sort_handler, true)
           sort_handler(other)

data/lib/lookbook/entities/entity.rb

@@ -1,27 +1,57 @@
 module Lookbook
   # Base entity class
   #
-  # @api private
+  # @api public
   class Entity
     include Comparable
     send(:include, Lookbook::Engine.routes.url_helpers) # YARD parsing workaround: https://github.com/lsegal/yard/issues/546
 
+    # @api private
     def initialize(lookup_path = nil)
       @lookup_path = lookup_path
     end
 
+    # @!group Identity
+
+    # Human-readable unique ID for the entity
+    #
+    # @return [String] The ID
     def id
       Utils.id(fetch_config(:id) { lookup_path.tr("/", "-") })
     end
 
+    # Parameter-safe entity name.
+    #
+    # @return [String] The name
     def name
       @_name ||= Utils.name(File.basename(@lookup_path))
     end
 
+    # Titlized name for use in navigation etc.
+    #
+    # Can be customized using the `@label` tag where supported.
+    #
+    # @return [String] The label
     def label
       @_label ||= fetch_config(:label) { name.titleize }
     end
 
+    # Entity type identifier
+    #
+    # @return [Symbol] The entity type
+    def type
+      @_type ||= self.class.name.gsub("Entity", "").demodulize.underscore.downcase.to_sym
+    end
+
+    # @!endgroup
+
+    # @!group Paths
+
+    # Canonical reference path.
+    #
+    # Used for generating URL paths and looking up entities.
+    #
+    # @return [String] The lookup path
     def lookup_path
       return @_lookup_path if @_lookup_path
 
@@ -32,23 +62,15 @@ module Lookbook
       @_lookup_path ||= PathUtils.strip_slashes(PathUtils.to_path(directory, name))
     end
 
-    def url_path
-      nil
-    end
+    alias_method :path, :lookup_path
+    deprecate path: :lookup_path, deprecator: Deprecation
 
-    def type
-      @_type ||= self.class.name.gsub("Entity", "").demodulize.underscore.downcase.to_sym
-    end
+    # @!endgroup
 
     def <=>(other)
       label <=> other.label
     end
 
-    alias_method :path, :lookup_path
-    alias_method :logical_path, :lookup_path
-
-    deprecate path: :lookup_path, deprecator: Deprecation
-
     protected
 
     def fetch_config(key, fallback = nil, &block)

data/lib/lookbook/entities/page_entity.rb

@@ -1,14 +1,18 @@
 module Lookbook
   # Represents a documentation page
   #
-  # @ignore methods
   # @api public
   class PageEntity < Entity
     include LocatableEntity
     include NavigableEntity
 
-    attr_reader :content, :sections
+    # @api private
+    attr_reader :content
 
+    # @api private
+    attr_reader :sections
+
+    # @api private
     def initialize(file_path)
       @file_path = Pathname(file_path)
       @base_directories = Engine.page_paths
@@ -18,50 +22,104 @@ module Lookbook
       @sections = []
     end
 
+    # @!group Identity
+
+    # Page title, as defined in frontmatter.
+    # Defaults to the page `label` if not provided.
+    #
+    # @return [String] The title
     def title
       @_title ||= fetch_config(:title, label)
     end
 
+    # @!endgroup
+
+    # @!group Frontmatter
+
+    # Merged data hash. Combines `data` set in frontmatter
+    # with any global default values.
+    #
+    # @return [Hash] The resolved data hash
+    def data
+      return @_data if @_data
+
+      config_data = fetch_config(:data, {})
+      @_data ||= config_data.is_a?(Hash) ? Store.new(config_data) : config_data
+    end
+
+    # @!endgroup
+
+    # @!group Predicates
+
+    # Whether the page is the default landing page.
+    #
+    # Set via the `landing` frontmatter property.
+    #
+    # @return [Boolean]
     def landing?
       @_landing ||= fetch_config(:landing, false)
     end
 
+    # Whether the page content should be rendered
+    # with the Markdown renderer.
+    #
+    # Set via the `markdown` frontmatter property.
+    #
+    # @return [Boolean]
     def markdown?
       @_markdown ||= fetch_config(:markdown) { file_path.to_s.match?(/(.*)\.md\.(.*)$/) }
     end
 
+    # Whether the page header will be shown.
+    #
+    # Set via the `header` frontmatter property.
+    #
+    # @return [Boolean]
     def header?
       @_header ||= fetch_config(:header, true)
     end
 
+    # Whether the page footer will be shown.
+    #
+    # Set via the `footer` frontmatter property.
+    #
+    # @return [Boolean]
     def footer?
       @_footer ||= fetch_config(:footer, true)
     end
 
-    def data
-      return @_data if @_data
+    # @!endgroup
 
-      config_data = fetch_config(:data, {})
-      @_data ||= config_data.is_a?(Hash) ? Store.new(config_data) : config_data
+    # @!group URLs
+
+    # The docs URL path for this page.
+    #
+    # @return [String] URL path
+    def docs_path
+      lookbook_page_path(lookup_path)
     end
 
+    alias_method :url_path, :docs_path
+
+    # @!endgroup
+
+    # @api private
     def search_terms
       label
     end
 
-    def url_path
-      lookbook_page_path(lookup_path)
-    end
-
+    # @api private
     def add_section(section)
       @sections << section
       @sections.sort_by! { |section| [section.priority, section.label] }
     end
 
+    # @api private
     def method_missing(method_name, *args, &block)
       method_name.to_s.end_with?("=") ? super : frontmatter.fetch(method_name, nil)
     end
 
+    # @api private
     def respond_to_missing?(method_name, include_private = false)
       frontmatter.key?(method_name) || super
     end

data/lib/lookbook/entities/page_section_entity.rb

@@ -1,4 +1,8 @@
 module Lookbook
+  # Represents a documentation page section.
+  #
+  # @ignore methods
+  # @api private
   class PageSectionEntity < PageEntity
     attr_accessor :parent
 

data/lib/lookbook/entities/preview_entity.rb

@@ -1,7 +1,6 @@
 module Lookbook
   # Represents a preview class
   #
-  # @ignore methods
   # @api public
   class PreviewEntity < Entity
     include AnnotatableEntity
@@ -10,8 +9,10 @@ module Lookbook
 
     delegate :render_args, to: :preview_class
 
+    # @api private
     attr_reader :preview_class
 
+    # @api private
     def initialize(code_object)
       @code_object = code_object
       @preview_class = code_object.path.constantize
@@ -25,61 +26,150 @@ module Lookbook
       @lookup_path = PathUtils.to_lookup_path(cleaned_path)
     end
 
+    # @!group Scenarios
+
+    # Get all scenarios defined in the preview class.
+    #
+    # @example :ruby
+    #   scenario_names = preview.scenarios.map(&:name)
+    #
+    # @return [Array<ScenarioEntity>] All scenarios for the preview
     def scenarios
       @_scenarios ||= ScenarioCollection.new(load_scenarios)
     end
 
+    alias_method :examples, :scenarios
+    deprecate examples: :scenarios, deprecator: Deprecation
+
+    # Find a specific scenario by (i.e. method) name
+    #
+    # @example :ruby
+    #   default_scenario_preview_path = preview.scenario(:default).preview_path
+    #
+    # @param scenario_name [Symbol, String] Name of the scenario
+    # @return [ScenarioEntity] The matching scenario, if found
+    # @return [nil] if no matching scenario was found
     def scenario(scenario_name)
       scenarios.find { |m| m.name == scenario_name.to_s }
     end
 
+    alias_method :example, :scenario
+    deprecate example: :scenario, deprecator: Deprecation
+
+    # Get all scenarios defined in the preview class that
+    # have not been hidden (by using the `@hidden` tag).
+    #
+    # @example :ruby
+    #   visible_scenario_names = preview.visible_scenarios.map(&:name)
+    #
+    # @return [Array<ScenarioEntity>] All visible scenarios for the preview
     def visible_scenarios
       @_visible_scenarios ||= ScenarioCollection.new(scenarios.select(&:visible?))
     end
 
+    # Get all scenarios defined in the preview class
+    # that are hidden (using the `@hidden` tag) and so
+    # will not show up in the navigation.
+    #
+    # @example :ruby
+    #   hidden_scenario_names = preview.hidden_scenarios.map(&:name)
+    #
+    # @return [Array<ScenarioEntity>] All hidden scenarios for the preview
+    def hidden_scenarios
+      @_hidden_scenarios ||= ScenarioCollection.new(scenarios.select(&:hidden?))
+    end
+
+    # The scenario used when a preview is rendered
+    # without explicity specifying a scenario.
+    #
+    # @example :ruby
+    #   default_scenario_name = preview.default_scenario.name
+    #
+    # @return [ScenarioEntity] The default scenario for this preview
     def default_scenario
       visible_scenarios.first
     end
 
+    # @!endgroup
+
+    # @!group Render Targets
+
+    # All 'render targets' (i.e. components or partials) that are known
+    # to be rendered within the scenarios defined within this preview.
+    #
+    # Render targets are guessed where possible (based on the preview class name)
+    # but can also be manually specified using the `@renders` tag.
+    #
+    # @example :ruby
+    #  "This preview renders: #{preview.render_targets.map(&:label).join(", ")}"
+    #
+    # @return [Array<RenderableEntity>] All known render targets used in the preview
     def render_targets
       @_render_targets ||= RenderTargetCollection.new(scenarios.flat_map(&:render_targets).uniq(&:lookup_path))
     end
 
+    alias_method :components, :render_targets
+
+    # @api private
     def render_target
       render_targets.first
     end
 
-    def display_options
-      global_options = Lookbook.config.preview_display_options
-      global_options.deep_merge(fetch_config(:display_options, {}))
-    end
+    # @api private
+    alias_method :component, :render_target
 
-    def layout
-      preview_class.instance_variable_get(:@layout)
-    end
+    # @!endgroup
 
-    def url_path
+    # @!group URLs
+
+    # The inspector URL path for this preview
+    #
+    # @return [String] URL path
+    def inspect_path
       lookbook_inspect_path(lookup_path)
     end
 
+    alias_method :url_path, :inspect_path
+
+    # The standalone preview URL path for this preview
+    #
+    # @return [String] URL path
+    def preview_path
+      lookbook_preview_path(lookup_path)
+    end
+
+    # @!endgroup
+
+    # The name of the associated preview class
+    #
+    # @return [String] Class name
     def preview_class_name
       preview_class.name
     end
 
+    # @api private
+    def file_name_base
+      @_file_name_slug ||= file_name(true).gsub(/(_component_preview|component_preview|preview)$/, "")
+    end
+
+    # @api private
+    def display_options
+      global_options = Lookbook.config.preview_display_options
+      global_options.deep_merge(fetch_config(:display_options, {}))
+    end
+
+    # @api private
+    def layout
+      preview_class.instance_variable_get(:@layout)
+    end
+
+    # @api private
     def guess_render_targets
       [preview_class.name.chomp("Preview").constantize&.name]
     rescue
       []
     end
 
-    alias_method :components, :render_targets
-    alias_method :component, :render_target
-    alias_method :examples, :scenarios
-    alias_method :example, :scenario
-
-    deprecate examples: :scenarios, deprecator: Deprecation
-    deprecate example: :scenario, deprecator: Deprecation
-
     protected
 
     def load_scenarios

data/lib/lookbook/entities/renderable_entity.rb

@@ -2,49 +2,87 @@ module Lookbook
   # Represents the component or view template partial
   # that is being rendered in a preview.
   #
-  # @ignore methods
   # @api public
   class RenderableEntity < Entity
     include LocatableEntity
 
+    # @api private
     def initialize(identifier)
       @identifier = identifier
       @base_directories = Engine.component_paths
       @file_path = PathUtils.determine_full_path(component? ? "#{name}.rb" : identifier, @base_directories)
       unless @file_path && File.exist?(@file_path)
-        raise LookbookError, "The render target #{@identifier} was not found."
+        raise Lookbook::Error, "The render target #{@identifier} was not found."
       end
       @lookup_path = PathUtils.to_lookup_path(relative_file_path)
     end
 
-    def component_class
-      @identifier.constantize if component?
-    end
+    # @!group Identity
 
+    # Parameter-safe entity name.
+    #
+    # @return [String]
     def name
       component? ? component_class.name.underscore : @identifier
     end
 
-    def template_file_path
-      component? ? Dir.glob("#{directory_path}/#{file_name(true)}.*.erb").first : file_path
+    # Entity type identifier.
+    # Returns `:component` for components and
+    # `:template` for view templates/partials.
+    #
+    # @return [Symbol] The entity type
+    def type
+      component? ? :component : :template
+    end
+
+    # @!endgroup
+
+    # @!group Components
+
+    # The associated component class (if the renderable is a component).
+    #
+    # @return [Class] The component class
+    def component_class
+      @identifier.constantize if component?
     end
 
+    # Whether or not the renderable is a component without a template.
+    #
+    # @return [Boolean] True if no template is present
     def inline?
       component? ? template_file_path.present? : false
     end
 
+    # Whether or not the renderable is a component
+    # (as opposed to a view template/partial).
+    #
+    # @return [Boolean] True if component
     def component?
       @identifier.first.upcase == @identifier.first &&
         !@identifier.include?(".") &&
         !@identifier.include?("/")
     end
 
+    # Whether or not the renderable is a view template/partial
+    # (as opposed to a component).
+    #
+    # @return [Boolean] True if component
     def template?
       !component?
     end
 
-    def type
-      component? ? :component : :template
+    # @!endgroup
+
+    # @!group Paths
+
+    # Full path to the component template (if present)
+    # or view template/partial.
+    #
+    # @return [Class] The component class
+    def template_file_path
+      component? ? Dir.glob("#{directory_path}/#{file_name(true)}.*.erb").first : file_path
     end
+
+    # @!endgroup
   end
 end

data/lib/lookbook/entities/rendered_scenario_entity.rb

@@ -1,31 +1,42 @@
 module Lookbook
-  # Represents a **rendered** preview scenario
+  # Represents a **rendered** preview scenario.
+  #
+  # Extends ScenarioEntity with an `output`
+  # method that returns the rendered HTML output.
+  #
+  # See the [ScenarioEntity](./scenario_entity) docs for other available methods.
   #
-  # @ignore methods
   # @api public
   class RenderedScenarioEntity
     delegate_missing_to :scenario
 
+    # @api private
     attr_reader :scenario
 
+    # @api private
     def initialize(scenario, output, params)
       @scenario = scenario
       @params = params
       @output = output
     end
 
+    # HTML output of the rendered scenario.
+    #
+    # @return [String] Rendered output
+    def output
+      @_output ||= CodeBeautifier.call(@output)
+    end
+
+    # @api private
     def source
       has_custom_template? ? template_source(template) : scenario.source
     end
 
+    # @api private
     def source_lang
       has_custom_template? ? template_lang(template) : scenario.source_lang
     end
 
-    def output
-      @_output ||= CodeBeautifier.call(@output)
-    end
-
     protected
 
     attr_reader :params