chore: Prototype pages optimizations and improvements to YARD docs

bridgetown-core/.yardopts

@@ -0,0 +1 @@
+-m markdown

bridgetown-core/lib/bridgetown-core/concerns/site/configurable.rb

@@ -1,18 +1,16 @@
 # frozen_string_literal: true
 
-module Bridgetown
-  module Site::Configurable
+class Bridgetown::Site
+  module Configurable
     # Set the site's configuration. This handles side-effects caused by
-    # changing values in the configuration.
+    #   changing values in the configuration.
     #
-    # @param config [Bridgetown::Configuration]
-    #   An instance of {Bridgetown::Configuration},
+    # @param config [Configuration]
+    #   An instance of {Configuration},
     #   containing the new configuration.
     #
-    # @return [Bridgetown::Configuration]
-    #   A new instance of {Bridgetown::Configuration}
-    #
-    # @see Bridgetown::Configuration
+    # @return [Configuration]
+    #   The processed instance of {Configuration}
     def config=(config)
       @config = config.clone
 
@@ -38,21 +36,21 @@ def config=(config)
     end
 
     def defaults_reader
-      @defaults_reader ||= DefaultsReader.new(self)
+      @defaults_reader ||= Bridgetown::DefaultsReader.new(self)
     end
 
     # Returns the current instance of {FrontmatterDefaults} or
-    # creates a new instance {FrontmatterDefaults} if it doesn't already exist.
+    #   creates a new instance {FrontmatterDefaults} if it doesn't already exist.
     #
     # @return [FrontmatterDefaults]
     #   Returns an instance of {FrontmatterDefaults}
     def frontmatter_defaults
-      @frontmatter_defaults ||= FrontmatterDefaults.new(self)
+      @frontmatter_defaults ||= Bridgetown::FrontmatterDefaults.new(self)
     end
 
     # Whether to perform a full rebuild without incremental regeneration.
-    # If either +override+["incremental"] or +config+["incremental"] are true,
-    # fully rebuild the site. If not, incrementally build the site.
+    #   If either `override["incremental"]` or `config["incremental"]` are true,
+    #   fully rebuild the site. If not, incrementally build the site.
     #
     # @param [Hash] override
     #   An override hash to override the current config value
@@ -63,11 +61,11 @@ def incremental?(override = {})
     end
 
     # Returns the current instance of {Publisher} or creates a new instance of
-    # {Publisher} if one doesn't exist.
+    #   {Publisher} if one doesn't exist.
     #
     # @return [Publisher] Returns an instance of {Publisher}
     def publisher
-      @publisher ||= Publisher.new(self)
+      @publisher ||= Bridgetown::Publisher.new(self)
     end
 
     # Prefix a path or paths with the {#root_dir} directory.
@@ -126,16 +124,16 @@ def in_cache_dir(*paths)
     end
 
     # The full path to the directory that houses all the registered collections
-    # for the current site.
+    #  for the current site.
     #
-    # If +@collections_path+ is specified use its value.
+    #  If `@collections_path` is specified use its value.
     #
-    # If +@collections+ is not specified and +config+["collections_dir"] is
-    # specified, prepend it with {#source} and assign it to
-    # {#collections_path}.
+    #  If `@collections` is not specified and `config["collections_dir"]` is
+    #  specified, prepend it with {#source} and assign it to
+    #  {#collections_path}.
     #
-    # If +@collections+ is not specified and +config+["collections_dir"] is not
-    # specified, assign {#source} to +@collections_path+
+    #  If `@collections` is not specified and `config["collections_dir"]` is not
+    #  specified, assign {#source} to `@collections_path`
     #
     # @return [String] Returns the full path to the collections directory
     # @see #config

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

@@ -1,27 +1,24 @@
 # frozen_string_literal: true
 
-module Bridgetown
-  module Site::Content
+class Bridgetown::Site
+  # Content is king!
+  module Content
     # Construct a Hash of Posts indexed by the specified Post attribute.
     #
-    # @param post_attr [String] The String name of the Post attribute.
-    #
-    # @example
-    #   Returns a hash like so: { attr => posts } where
+    # Returns a hash like so: `{ attr => posts }` where:
     #
-    #   attr  - One of the values for the requested attribute.
+    # * `attr` - One of the values for the requested attribute.
+    # * `posts` - The array of Posts with the given attr value.
     #
-    #   posts - The Array of Posts with the given attr value.
+    # @param post_attr [String] The String name of the Post attribute.
     #
     # @example
-    #
     #   post_attr_hash('categories')
     #   # => { 'tech' => [<Post A>, <Post B>],
     #   #      'ruby' => [<Post B>] }
     #
     # @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.
@@ -36,7 +33,7 @@ def post_attr_hash(post_attr)
     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.
+    #  and each value is a post which contains the key.
     # @example
     #   tags
     #   # => { 'tech': [<Post A>, <Post B>],
@@ -48,7 +45,7 @@ def 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.
+    #  a key and each value is a post which contains the key.
     # @example
     #   categories
     #   # => { 'tech': [<Post A>, <Post B>],
@@ -60,8 +57,8 @@ def categories
       post_attr_hash("categories")
     end
 
-    # Returns the value of +data+["site_metadata"] or creates a new instance of
-    # +HashWithDotAccess::Hash+
+    # Returns the value of `data["site_metadata"]` or creates a new instance of
+    #   `HashWithDotAccess::Hash`
     # @return [Hash] Returns a hash of site metadata
     def metadata
       data["site_metadata"] ||= HashWithDotAccess::Hash.new
@@ -98,22 +95,21 @@ def metadata
     #
     # @see #post_attr_hash
     def site_payload
-      Drops::UnifiedPayloadDrop.new self
+      Bridgetown::Drops::UnifiedPayloadDrop.new self
     end
     alias_method :to_liquid, :site_payload
 
-    # The list of {#collections} and their corresponding {Bridgetown::Collection} instances.
+    # The list of collections labels and their corresponding {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 set, a new instance of {Collection} is created
+    #  for each entry in the collections configuration.
     #
-    # If +config+["collections"] is not specified, a blank hash is returned.
+    #  If `config["collections"]` is not specified, a blank hash is returned.
     #
-    # @return [Hash{String, Symbol => Bridgetown::Collection}] A Hash
+    # @return [Hash{String, Symbol => 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(
         HashWithDotAccess::Hash.new
@@ -124,8 +120,8 @@ def collections
 
     # An array of collection names.
     # @return [Array<String>] 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
+    #   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"]
@@ -141,7 +137,7 @@ def collection_names
     end
 
     # Get all documents.
-    # @return [Array<Bridgetown::Document>] an array of documents from the
+    # @return [Array<Document>] an array of documents from the
     # configuration
     def documents
       collections.each_with_object(Set.new) do |(_, collection), set|
@@ -151,8 +147,8 @@ def documents
 
     # Get the documents to be written
     #
-    # @return [Array<Bridgetown::Document>] an array of documents which should be
-    # written and that +respond_to :write?+
+    # @return [Array<Document>] an array of documents which should be
+    #   written and that `respond_to :write?`
     # @see #documents
     # @see Collection
     def docs_to_write
@@ -161,17 +157,16 @@ def docs_to_write
 
     # Get all posts.
     #
-    # @return [Collection] A #Collection of posts. Returns +#collections+["posts"]
-    # @return [Collection] Return a new #Collection if +#collections+["posts"] is nil
+    # @return [Collection] Returns {#collections}`["posts"]`, creating it if need be
     # @see Collection
     def posts
-      collections["posts"] ||= Collection.new(self, "posts")
+      collections["posts"] ||= Bridgetown::Collection.new(self, "posts")
     end
 
     # Get the static files to be written
     #
-    # @return [Array<Bridgetown::StaticFile>] an array of files which should be
-    # written and that +respond_to :write?+
+    # @return [Array<StaticFile>] an array of files which should be
+    #   written and that `respond_to :write?`
     # @see #static_files
     # @see StaticFile
     def static_files_to_write

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

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-module Bridgetown
-  module Site::Extensible
+class Bridgetown::Site
+  module Extensible
     # Load necessary libraries, plugins, converters, and generators.
-    # @see Bridgetown::Converter
-    # @see Bridgetown::Generator
+    # @see Converter
+    # @see Generator
     # @see PluginManager
     # @return [void]
     def setup
@@ -14,7 +14,7 @@ def setup
     end
 
     # Run all Generators.
-    # @see Bridgetown::Generator
+    # @see Generator
     # @return [void]
     def generate
       generators.each do |generator|
@@ -33,10 +33,10 @@ def generate
       end
     end
 
-    # Get the implementation class for the given Converter.
-    # @param klass [Object] The Class of the Converter to fetch.
-    # @return [Bridgetown::Converter] Returns the {Bridgetown::Converter}
-    #   instance implementing the given +Converter+.
+    # Get the implementation for the given Converter class.
+    # @param klass [Class] The Class of the Converter to fetch.
+    # @return [Converter] Returns the {Converter}
+    #   instance implementing the given `Converter` class.
     def find_converter_instance(klass)
       @find_converter_instance ||= {}
       @find_converter_instance[klass] ||= begin
@@ -45,11 +45,11 @@ def find_converter_instance(klass)
       end
     end
 
-    # Create an array of instances of the subclasses of the class or module
+    # Create an array of instances of the subclasses of the class
     #   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+.
+    # @param klass [Class] - class which is the parent of the subclasses.
+    # @return [Array<Converter, Generator>] Returns an array of instances of
+    #   subclasses of `klass`.
     def instantiate_subclasses(klass)
       klass.descendants.sort.map do |c|
         c.new(config)

bridgetown-core/lib/bridgetown-core/concerns/site/localizable.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-module Bridgetown
-  module Site::Localizable
+class Bridgetown::Site
+  module Localizable
+    # Returns the current and/or default configured locale
+    # @return String
     def locale
       if @locale
         @locale
@@ -13,6 +15,8 @@ def locale
       end
     end
 
+    # Sets the current locale for the site
+    # @param new_locale [String] for example: "en" for English, "es" for Spanish
     def locale=(new_locale)
       I18n.locale = @locale = new_locale.to_sym
     end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module Bridgetown
-  module Site::Processable
+class Bridgetown::Site
+  module Processable
     # Reset, Read, Generate, Render, Cleanup, Process, and Write this Site to output.
     # @return [void]
     # @see #reset
@@ -22,14 +22,15 @@ def process
 
     # rubocop:disable Metrics/AbcSize
 
-    # Reset Site details.
+    # Reset all in-memory data and content.
     # @return [void]
     def reset
-      self.time = if config["time"]
-                    Utils.parse_date(config["time"].to_s, "Invalid time in bridgetown.config.yml.")
-                  else
-                    Time.now
-                  end
+      self.time = Time.now
+      if config["time"]
+        self.time = Bridgetown::Utils.parse_date(
+          config["time"].to_s, "Invalid time in bridgetown.config.yml."
+        )
+      end
       self.layouts = HashWithDotAccess::Hash.new
       self.pages = []
       self.static_files = []
@@ -50,7 +51,7 @@ def reset
 
     # rubocop:enable Metrics/AbcSize
 
-    # Read Site data from disk and load it into internal data structures.
+    # Read data from disk and load it into internal memory.
     # @return [void]
     def read
       Bridgetown::Hooks.trigger :site, :pre_read, self