bridgetown-core 0.15.0.beta1 → 0.16.0.beta1

data/lib/bridgetown-core/concerns/site/content.rb

@@ -4,17 +4,24 @@ module Bridgetown
   module Site::Content
     # Construct a Hash of Posts indexed by the specified Post attribute.
     #
-    # post_attr - The String name of the Post attribute.
+    # @param post_attr [String] The String name of the Post attribute.
     #
-    # Examples
+    # @example
+    #   Returns a hash like so: { attr => posts } where
+    #
+    #   attr  - One of the values for the requested attribute.
+    #
+    #   posts - The Array of Posts with the given attr value.
+    #
+    # @example
     #
     #   post_attr_hash('categories')
     #   # => { 'tech' => [<Post A>, <Post B>],
     #   #      'ruby' => [<Post B>] }
     #
-    # Returns the Hash: { attr => posts } where
-    #   attr  - One of the values for the requested attribute.
-    #   posts - The Array of Posts with the given attr value.
+    # @return [Hash{String, Symbol => Array<Post>}]
+    #   Returns a hash of !{attr => posts}
+    #
     def post_attr_hash(post_attr)
       # Build a hash map based on the specified post attribute ( post attr =>
       # array of posts ) then sort each array in reverse order.
@@ -28,41 +35,85 @@ module Bridgetown
       end
     end
 
+    # Returns a hash of "tags" using {#post_attr_hash} where each tag is a key
+    # and each value is a post which contains the key.
+    # @example
+    #   tags
+    #   # => { 'tech': [<Post A>, <Post B>],
+    #   #      'ruby': [<Post C> }
+    # @return [Hash{String, Array<Post>}] Returns a hash of all tags and their corresponding posts
+    # @see post_attr_hash
     def tags
       post_attr_hash("tags")
     end
 
+    # Returns a hash of "categories" using {#post_attr_hash} where each tag is
+    # a key and each value is a post which contains the key.
+    # @example
+    #   categories
+    #   # => { 'tech': [<Post A>, <Post B>],
+    #   #      'ruby': [<Post C> }
+    # @return [Hash{String, Array<Post>}] Returns a hash of all categories and
+    #   their corresponding posts
+    # @see post_attr_hash
     def categories
       post_attr_hash("categories")
     end
 
+    # Returns the value of +data+["site_metadata"] or creates a new instance of
+    # +ActiveSupport::HashWithIndifferentAccess+
+    # @return [Hash] Returns a hash of site metadata
     def metadata
       data["site_metadata"] ||= ActiveSupport::HashWithIndifferentAccess.new
     end
 
     # The Hash payload containing site-wide data.
     #
-    # Returns the Hash: { "site" => data } where data is a Hash with keys:
-    #   "time"       - The Time as specified in the configuration or the
-    #                  current time if none was specified.
-    #   "posts"      - The Array of Posts, sorted chronologically by post date
-    #                  and then title.
-    #   "pages"      - The Array of all Pages.
-    #   "html_pages" - The Array of HTML Pages.
-    #   "categories" - The Hash of category values and Posts.
-    #                  See Site#post_attr_hash for type info.
-    #   "tags"       - The Hash of tag values and Posts.
-    #                  See Site#post_attr_hash for type info.
+    # @example
+    #   site_payload
+    #   # => { "site" => data } Where data is a Hash. See example below
+    #
+    #   site = site_payload["site"]
+    #   # => Returns a Hash with the following keys:
+    #   #
+    #   # site["time"]       - The Time as specified in the configuration or the
+    #   #                      current time if none was specified.
+    #   #
+    #   # site["posts"]      - The Array of Posts, sorted chronologically by post date
+    #   #                      and then title.
+    #   #
+    #   # site["pages"]      - The Array of all Pages.
+    #   #
+    #   # site["html_pages"] - The Array of HTML Pages.
+    #   #
+    #   # site["categories"] - The Hash of category values and Posts.
+    #   #                      See Site#post_attr_hash for type info.
+    #   #
+    #   # site["tags"]       - The Hash of tag values and Posts.
+    #   #                      See Site#post_attr_hash for type info.
+    #
+    # @return [Hash] Returns a hash in the structure of { "site" => data }
+    #
+    #   See above example for usage.
+    #
+    # @see #post_attr_hash
     def site_payload
       Drops::UnifiedPayloadDrop.new self
     end
     alias_method :to_liquid, :site_payload
 
-    # The list of collections and their corresponding Bridgetown::Collection instances.
-    # If config['collections'] is set, a new instance is created
-    # for each item in the collection, a new hash is returned otherwise.
+    # The list of {#collections} and their corresponding {Bridgetown::Collection} instances.
+    #
+    # If +config+['collections'] is set, a new instance of {Bridgetown::Collection} is created
+    # for each entry in the collections configuration.
+    #
+    # If +config+["collections"] is not specified, a blank hash is returned.
     #
-    # Returns a Hash containing collection name-to-instance pairs.
+    # @return [Hash{String, Symbol => Bridgetown::Collection}] A Hash
+    #   containing a collection name-to-instance pairs.
+    #
+    # @return [Hash] Returns a blank hash if no items found
+    # @see Collection
     def collections
       @collections ||= collection_names.each_with_object(
         ActiveSupport::HashWithIndifferentAccess.new
@@ -71,10 +122,11 @@ module Bridgetown
       end
     end
 
-    # The list of collection names.
-    #
-    # Returns an array of collection names from the configuration,
-    #   or an empty array if the `collections` key is not set.
+    # An array of collection names.
+    # @return [Array<Collection>] an array of collection names from the configuration,
+    #   or an empty array if the +config+["collections"] key is not set.
+    # @raise ArgumentError Raise an error if +config+["collections"] is not
+    #   an Array or a Hash
     def collection_names
       case config["collections"]
       when Hash
@@ -88,22 +140,29 @@ module Bridgetown
       end
     end
 
-    # Get all the documents
-    #
-    # Returns an Array of all Documents
+    # Get all documents.
+    # @return [Array<String>] an array of documents from the configuration
     def documents
       collections.each_with_object(Set.new) do |(_, collection), set|
         set.merge(collection.docs).merge(collection.files)
       end.to_a
     end
 
-    # Get the to be written documents
+    # Get the documents to be written
     #
-    # Returns an Array of Documents which should be written
+    # @return [Array<String, File>] an Array of Documents which should be written and
+    #   that +respond_to :write?+
+    # @see #documents
+    # @see Collection
     def docs_to_write
       documents.select(&:write?)
     end
 
+    # Get all posts.
+    #
+    # @return [Collection] A #Collection of posts. Returns +#collections+["posts"]
+    # @return [Collection] Return a new #Collection if +#collections+["posts"] is nil
+    # @see Collection
     def posts
       collections["posts"] ||= Collection.new(self, "posts")
     end

data/lib/bridgetown-core/concerns/site/extensible.rb

@@ -3,17 +3,19 @@
 module Bridgetown
   module Site::Extensible
     # Load necessary libraries, plugins, converters, and generators.
-    #
-    # Returns nothing.
+    # @see Bridgetown::Converter
+    # @see Bridgetown::Generator
+    # @see PluginManager
+    # @return [void]
     def setup
       plugin_manager.require_plugin_files
       self.converters = instantiate_subclasses(Bridgetown::Converter)
       self.generators = instantiate_subclasses(Bridgetown::Generator)
     end
 
-    # Run each of the Generators.
-    #
-    # Returns nothing.
+    # Run all Generators.
+    # @see Bridgetown::Generator
+    # @return [void]
     def generate
       generators.each do |generator|
         start = Time.now
@@ -32,8 +34,9 @@ module Bridgetown
     end
 
     # Get the implementation class for the given Converter.
-    # Returns the Converter instance implementing the given Converter.
-    # klass - The Class of the Converter to fetch.
+    # @param klass [Object] The Class of the Converter to fetch.
+    # @return [Bridgetown::Converter] Returns the {Bridgetown::Converter}
+    #   instance implementing the given +Converter+.
     def find_converter_instance(klass)
       @find_converter_instance ||= {}
       @find_converter_instance[klass] ||= begin
@@ -42,11 +45,11 @@ module Bridgetown
       end
     end
 
-    # klass - class or module containing the subclasses.
-    # Returns array of instances of subclasses of parameter.
-    # Create array of instances of the subclasses of the class or module
-    # passed in as argument.
-
+    # Create an array of instances of the subclasses of the class or module
+    #   passed in as argument.
+    # @param klass [Class, Module] - class or module containing the subclasses.
+    # @return [Array<Object>] Returns an array of instances of subclasses of
+    #   +klass+.
     def instantiate_subclasses(klass)
       klass.descendants.sort.map do |c|
         c.new(config)

data/lib/bridgetown-core/concerns/site/processable.rb

@@ -2,9 +2,14 @@
 
 module Bridgetown
   module Site::Processable
-    # Public: Read, process, and write this Site to output.
-    #
-    # Returns nothing.
+    # Reset, Read, Generate, Render, Cleanup, Process, and Write this Site to output.
+    # @return [void]
+    # @see #reset
+    # @see #read
+    # @see #generate
+    # @see #render
+    # @see #cleanup
+    # @see #write
     def process
       reset
       read
@@ -16,10 +21,9 @@ module Bridgetown
     end
 
     # rubocop:disable Metrics/AbcSize
-    #
+
     # Reset Site details.
-    #
-    # Returns nothing
+    # @return [void]
     def reset
       self.time = if config["time"]
                     Utils.parse_date(config["time"].to_s, "Invalid time in bridgetown.config.yml.")
@@ -43,11 +47,11 @@ module Bridgetown
       Bridgetown::Cache.clear_if_config_changed config
       Bridgetown::Hooks.trigger :site, :after_reset, self
     end
+
     # rubocop:enable Metrics/AbcSize
 
     # Read Site data from disk and load it into internal data structures.
-    #
-    # Returns nothing.
+    # @return [void]
     def read
       Bridgetown::Hooks.trigger :site, :pre_read, self
       reader.read
@@ -58,8 +62,6 @@ module Bridgetown
     private
 
     # Limits the current posts; removes the posts which exceed the limit_posts
-    #
-    # Returns nothing
     def limit_posts!
       if limit_posts.positive?
         limit = posts.docs.length < limit_posts ? posts.docs.length : limit_posts

data/lib/bridgetown-core/concerns/site/renderable.rb

@@ -3,8 +3,7 @@
 module Bridgetown
   module Site::Renderable
     # Render the site to the destination.
-    #
-    # Returns nothing.
+    # @return [void]
     def render
       payload = site_payload
 
@@ -18,6 +17,14 @@ module Bridgetown
       Bridgetown::Hooks.trigger :site, :post_render, self, payload
     end
 
+    # Executes inline Ruby frontmatter if
+    # +ENV+["BRIDGETOWN_RUBY_IN_FRONTMATTER"] equals "true"
+    #
+    # @example
+    #   calculation: !ruby/string:Rb |
+    #     [2 * 4, 5 + 2].min
+    # @return [void]
+    # @see https://www.bridgetownrb.com/docs/front-matter#ruby-front-matter
     def execute_inline_ruby_for_layouts!
       return unless config.should_execute_inline_ruby?
 
@@ -26,6 +33,10 @@ module Bridgetown
       end
     end
 
+    # Renders all documents
+    # @param payload [Hash] A hash of site data.
+    # @return [void]
+    # @see Bridgetown::Site::Content#site_payload
     def render_docs(payload)
       collections.each_value do |collection|
         collection.docs.each do |document|
@@ -34,17 +45,25 @@ module Bridgetown
       end
     end
 
+    # Renders all pages
+    # @param payload [Hash] A hash of site data.
+    # @return [void]
+    # @see Bridgetown::Site::Content#site_payload
     def render_pages(payload)
       pages.each do |page|
         render_regenerated(page, payload)
       end
     end
 
+    # Regenerates a site using {Bridgetown::Renderer}
+    # @param document [Post] The document to regenerate.
+    # @param payload [Hash] A hash of site data.
+    # @return [void]
+    # @see Bridgetown::Renderer
     def render_regenerated(document, payload)
       return unless regenerator.regenerate?(document)
 
-      document.output = Bridgetown::Renderer.new(self, document, payload).run
-      document.trigger_hooks(:post_render)
+      Bridgetown::Renderer.new(self, document, payload).run
     end
   end
 end

data/lib/bridgetown-core/concerns/site/writable.rb

@@ -4,14 +4,14 @@ module Bridgetown
   module Site::Writable
     # Remove orphaned files and empty directories in destination.
     #
-    # Returns nothing.
+    # @return [void]
     def cleanup
       @cleaner.cleanup!
     end
 
     # Write static files, pages, and posts.
     #
-    # Returns nothing.
+    # @return [void]
     def write
       each_site_file do |item|
         item.write(dest) if regenerator.regenerate?(item)
@@ -20,6 +20,20 @@ module Bridgetown
       Bridgetown::Hooks.trigger :site, :post_write, self
     end
 
+    # Yields the pages from {#pages}, {#static_files}, and {#docs_to_write}.
+    #
+    # @yieldparam item [Document, Page, StaticFile] Yields a
+    # {#Bridgetown::Page}, {#Bridgetown::StaticFile}, or
+    # {#Bridgetown::Document} object.
+    #
+    # @return [void]
+    #
+    # @see #pages
+    # @see #static_files
+    # @see #docs_to_write
+    # @see Page
+    # @see StaticFile
+    # @see Document
     def each_site_file
       %w(pages static_files docs_to_write).each do |type|
         send(type).each do |item|

data/lib/bridgetown-core/concerns/validatable.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Validatable
+    # FIXME: there should be ONE TRUE METHOD to read the YAML frontmatter
+    # in the entire project. Both this and the equivalent Document method
+    # should be extracted and generalized.
+    #
+    # Read the YAML frontmatter.
+    #
+    # base - The String path to the dir containing the file.
+    # name - The String filename of the file.
+    # opts - optional parameter to File.read, default at site configs
+    #
+    # Returns nothing.
+    # rubocop:disable Metrics/AbcSize
+    def read_yaml(base, name, opts = {})
+      filename = File.join(base, name)
+
+      begin
+        self.content = File.read(@path || site.in_source_dir(base, name),
+                                 **Utils.merged_file_read_opts(site, opts))
+        if content =~ Document::YAML_FRONT_MATTER_REGEXP
+          self.content = $POSTMATCH
+          self.data = SafeYAML.load(Regexp.last_match(1))&.with_indifferent_access
+        end
+      rescue Psych::SyntaxError => e
+        Bridgetown.logger.warn "YAML Exception reading #{filename}: #{e.message}"
+        raise e if site.config["strict_front_matter"]
+      rescue StandardError => e
+        Bridgetown.logger.warn "Error reading file #{filename}: #{e.message}"
+        raise e if site.config["strict_front_matter"]
+      end
+
+      self.data ||= ActiveSupport::HashWithIndifferentAccess.new
+
+      validate_data! filename
+      validate_permalink! filename
+
+      self.data
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # FIXME: why doesn't Document validate data too?
+    def validate_data!(filename)
+      unless self.data.is_a?(Hash)
+        raise Errors::InvalidYAMLFrontMatterError,
+              "Invalid YAML front matter in #{filename}"
+      end
+    end
+
+    # FIXME: Layouts don't have permalinks...d'oh
+    def validate_permalink!(filename)
+      if self.data["permalink"]&.to_s&.empty?
+        raise Errors::InvalidPermalinkError, "Invalid permalink in #{filename}"
+      end
+    end
+  end
+end

data/lib/bridgetown-core/configuration.rb

@@ -19,6 +19,7 @@ module Bridgetown
       "data_dir"             => "_data",
       "components_dir"       => "_components",
       "includes_dir"         => "_includes",
+      "partials_dir"         => "_partials",
       "collections"          => {},
 
       # Handling Reading