bridgetown-core 2.1.0.beta3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d881ab4b2b24a8b1c911d71df820dcd9c386de520344347f7ee8a5a5109f469d
-  data.tar.gz: 4bf2e4d05fc55afe7912688404912cd7198308b90a9f47efd15aaab315fb7658
+  metadata.gz: 4f37e7273caf13736dccb6a376882b50b2c36c4ead3c70456800f9e2ce2f83af
+  data.tar.gz: aff912422ccd046462db776b59ca3f6a5dd613d9e0635e8bc9815b8411ff56d2
 SHA512:
-  metadata.gz: d34714e2e7a93ed5a6d44e020c8a9079545ccddc6d3f5dba1e19c860d17fd4813fc493a56ba967d85c6f1e9ea8a21309ab0f44009f6b8bbf15b4a14abed0a5a8
-  data.tar.gz: 16517250a53acfce9f4b775cec57b99a6e0aa09e4077822a537e9e75ac84d3fdda98b931fd58fe99711319d2bfe89b9ebc1e67cd5301148da8715673c11beb18
+  metadata.gz: fa2cba9af2d353e02e6a1bc725f6e86fdfd4c0ca5f8855643c41f26c7ed3f29fcd8e72c4638268560c5983643b056fdc5837dc1450ae8336148d4e5ace80979c
+  data.tar.gz: 54bbee47d175e53a34f104880ede10e9688eafbb436b6656b7f791ffef81aee343bf21c7deccede2b2eecafc6af5937d6ec82a8a51debe489585d9d99cb34078

data/lib/bridgetown-core/collection.rb

@@ -150,7 +150,7 @@ module Bridgetown
     alias_method :directory, :absolute_path
 
     # The full path to the folder containing the collection, with
-    #   optional subpaths.
+    # optional subpaths.
     #
     # @param *files [Array<String>] any other path pieces relative to the
     #   folder to append to the path
@@ -190,7 +190,7 @@ module Bridgetown
 
     # Produce a sanitized label name
     # Label names may not contain anything but alphanumeric characters,
-    #   underscores, and hyphens.
+    # underscores, and hyphens.
     #
     # @param label [String] the possibly-unsafe label
     # @return [String] sanitized version of the label.
@@ -210,7 +210,7 @@ module Bridgetown
     end
 
     # Whether the collection's resources ought to be written as individual
-    #   files in the output.
+    # files in the output.
     #
     # @return [Boolean] true if the 'write' metadata is true, false otherwise.
     def write?

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

@@ -45,7 +45,7 @@ class Bridgetown::Site
     end
 
     # Returns the current instance of {FrontMatter::Defaults} or
-    #   creates a new instance {FrontMatter::Defaults} if it doesn't already exist.
+    # creates a new instance {FrontMatter::Defaults} if it doesn't already exist.
     #
     # @return [FrontMatter::Defaults]
     #   Returns an instance of {FrontMatter::Defaults}

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

@@ -48,7 +48,7 @@ class Bridgetown::Site
     end
 
     # Create an array of instances of the subclasses of the class
-    #   passed in as argument.
+    # passed in as argument.
     #
     # @param klass [Class] class which is the parent of the subclasses.
     # @return [Array<Converter, Generator>] Returns an array of instances of

data/lib/bridgetown-core/configuration/configuration_dsl.rb

@@ -7,7 +7,18 @@ module Bridgetown
 
       attr_reader :context
 
-      # @yieldself [ConfigurationDSL]
+      # Initialize a Bridgetown plugin, optionally passing along configuration data. By default,
+      # requires the associated Ruby gem as well, but this can be switched off for local
+      # initializer files.
+      #
+      # @param name [Symbol]
+      # @param require_gem [Boolean] set `false` if you don't want the named gem to be required
+      # @param require_initializer [Boolean] set `false` if the named file in your `config` folder
+      #   shouldn't get processed as an initializer
+      # @param kwargs [Hash] pass keyword arguments as configuration along to the plugin. This can
+      #   also be accomplished via a block using "Ruby front matter" syntax
+      # @yieldreceiver [ConfigurationDSL]
+      # @return [void]
       def init(name, require_gem: true, require_initializer: true, **kwargs, &block) # rubocop:todo Metrics
         return if @scope.initializers.key?(name.to_sym) &&
           @scope.initializers[name.to_sym].completed
@@ -35,18 +46,40 @@ module Bridgetown
         initializer.completed = true
       end
 
+      # Execute the provided block for configuration only if the current context matches the
+      # provided criteria.
+      #
+      # @param context [Symbol] supply one or more contexts for execution. Generally these are
+      #   `:static`, `:console`, `:rake`, and `:server`
+      # @return [void]
       def only(*context, &)
         return unless context.any? { _1 == @context }
 
         instance_exec(&)
       end
 
+      # Do not execute the provided block for configuration if the current context matches the
+      # provided criteria.
+      #
+      # @param context [Symbol] supply one or more contexts for avoiding execution. Generally these
+      #   are `:static`, `:console`, `:rake`, and `:server`
+      # @return [void]
       def except(*context, &)
         return if context.any? { _1 == @context }
 
         instance_exec(&)
       end
 
+      # Provides a wrapper around the `register_one` method of the `Hooks` class.
+      #
+      # @see Bridgetown::Hooks.register_one
+      # @param owner [Symbol] name of the owner (`:site`, `:resource`, etc.)
+      # @param event [Symbol] name of the event (`:pre_read`, `:post_render`, etc.)
+      # @param priority [Integer, Symbol] either `:low`, `:normal`, or `:high`, or an integer.
+      #   Default is normal (20)
+      # @yield the block will be called when the event is triggered. Typically it receives at
+      #   least one argument.
+      # @yieldparam obj the object which triggered the event hook
       def hook(
         owner,
         event,
@@ -56,10 +89,20 @@ module Bridgetown
         Bridgetown::Hooks.register_one(owner, event, priority:, reloadable: false, &)
       end
 
+      # Used by plugins to supply a source manifest.
+      #
+      # @see SourceManifest.new
+      # @return [void]
       def source_manifest(**)
         @scope.source_manifests << SourceManifest.new(**)
       end
 
+      # Used by plugins to register the provided Builder class, or alternatively
+      # register an "inline builder" by defining the class body in a block using the
+      # provided symbol as the class name.
+      #
+      # @param klass [Class<Bridgetown::Builder>, Symbol]
+      # @return [void]
       def builder(klass = nil, &)
         return klass.register if klass.is_a?(Class) && klass < Bridgetown::Builder
 
@@ -72,10 +115,18 @@ module Bridgetown
         )
       end
 
+      # Define an initializer block which is called when the Roda server is being configured.
+      #
+      # @yieldparam app [Class<Roda>]
+      # @return [void]
       def roda(&block)
         @scope.roda_initializers << block
       end
 
+      # Set the TZ environment variable to use the timezone specified
+      #
+      # @param timezone [String] the IANA Time Zone
+      # @return [void]
       def timezone(new_timezone)
         @data[:timezone] = new_timezone
         Bridgetown.set_timezone(new_timezone)
@@ -112,6 +163,8 @@ module Bridgetown
                      end
       end
 
+      # Similar to `init` but it simply prints out a list of the configuration options accepted
+      # as keyword arguments by the initializer
       def reflect(name, require_gem: true, require_initializer: true)
         initializer = _setup_initializer(
           name:, require_gem:, require_initializer:
@@ -130,9 +183,14 @@ module Bridgetown
         initializer.block.parameters.each do |param|
           next if param[0] == :opt
 
+          option = param[1].to_s
+          option = "** #{option}" if param[0] == :keyrest
+
           Bridgetown.logger.info("",
-                                 "* #{param[1].to_s.cyan}#{" (required)" if param[0] == :keyreq}")
+                                 "- #{option.cyan}#{" (required)" if param[0] == :keyreq}")
         end
+
+        nil
       end
 
       # @return [Bridgetown::Configuration::Initializer]
@@ -156,6 +214,90 @@ module Bridgetown
       def _run_builtins!
         init :streamlined
       end
+
+      ### Document configuration options ###
+      # TODO: many more to follow!
+
+      # @!method url(url)
+      #   Sets the base URL for absolute links. (This will be overridden with something like
+      #   `localhost:4000` in development.)
+      #   @param url [String]
+
+      # @!method source(path)
+      #   Change the directory where Bridgetown will read content files
+      #   @param path [String] - default: `src`
+
+      # @!method destination(path)
+      #   Change the directory where Bridgetown will write files
+      #   @param path [String] - default: `output`
+
+      # @!method template_engine(engine)
+      #   Change the template engine Bridgetown uses by default to process content files
+      #   @param engine [Symbol] - default: `:erb`, alternatives: `:serbea`, `:liquid`
+
+      # @!method permalink(style)
+      #   Change the default permalink style or template used by pages & blog posts
+      #   @param style [String] - default: `:pretty`, alternatives: `:pretty_ext`, `:simple`,
+      #     `:simple_ext`
+
+      # @!method fast_refresh(bool)
+      #   Control the behavior of Bridgetown's live reload functionality in development
+      #   @param bool [Boolean] - default: `true`
+
+      # @!method exclude(files_list)
+      #   Exclude source directories and/or files from the build conversion
+      #   @param files_list [Array<String>]
+
+      # @!method include(files_list)
+      #   Force inclusion of directories and/or files in the conversion (e.g. starting with
+      #   underscores or dots)
+      #   @param files_list [Array<String>]
+
+      # @!method keep_files(files_list)
+      #   Files to keep when clobbering the site destination (aka not generated in typical
+      #   Bridgetown builds)
+      #   @param files_list [Array<String>]
+
+      # @!method autoload_paths
+      #   Add paths to the Zeitwerk autoloader. Use a `config.defaults << "..."` syntax or a more
+      #   advanced hash config
+      #   @example Add a new path for autoloading and eager load on boot
+      #       config.autoload_paths << {
+      #         path: "loadme",
+      #         eager: true
+      #       }
+
+      # @!method additional_watch_paths(paths)
+      #   Watch additional directories for reloads not normally covered by autoloader
+      #   (relative to project root)
+      #   @param paths [Array<String>]
+
+      # @!method timezone(zone)
+      #   Set the time zone for site generation, using IANA Time Zone Database
+      #   @param zone [String]
+
+      # @!method defaults
+      #   Use a `config.defaults << {...}` syntax to add front matter defaults
+      #   @example Set a default layout for a collection
+      #       config.defaults << {
+      #         scope: { collection: :docs },
+      #         values: { layout: :default },
+      #       }
+
+      # @!method pagination
+      #   Enable and configure the settings for the paginator
+      #   @example Basic setup
+      #       pagination do
+      #         enabled true
+      #       end
+
+      # @!method base_path(url)
+      #   Optionally host your site off a path, e.g. `/blog`
+      #   @param url [String] - default: `/`
+
+      # @!method inflector
+      #   Configure the inflector to add new inflection types, based on `Dry::Inflector`
+      #   @return [Bridgetown::Foundation::Inflector]
     end
   end
 end

data/lib/bridgetown-core/configuration.rb

@@ -148,6 +148,12 @@ module Bridgetown
       end
     end
 
+    def initializers_dsl(context:)
+      ConfigurationDSL.new(scope: self, data: self).tap do |dsl|
+        dsl.instance_variable_set(:@context, context)
+      end
+    end
+
     def run_initializers!(context:) # rubocop:todo Metrics/AbcSize, Metrics/CyclomaticComplexity
       initializers_file = File.join(root_dir, "config", "initializers.rb")
       unless File.file?(initializers_file)
@@ -166,8 +172,7 @@ module Bridgetown
       Bridgetown.logger.debug "", initializers_file
       self.init_params = {}
       cached_url = url&.include?("//localhost") ? url : nil
-      dsl = ConfigurationDSL.new(scope: self, data: self)
-      dsl.instance_variable_set(:@context, context)
+      dsl = initializers_dsl(context:)
       dsl.instance_exec(dsl, &init_init.block)
       dsl._run_builtins!
       self.url = cached_url if cached_url # restore local development URL if need be

data/lib/bridgetown-core/hooks.rb

@@ -68,7 +68,7 @@ module Bridgetown
     # @yield the block will be called when the event is triggered. Typically it receives at
     #   least one argument.
     # @yieldparam obj the object which triggered the event hook
-    # @return [Proc] the block that was pased in
+    # @return [Proc] the block that was passed in
     def self.register_one(owner, event, priority: DEFAULT_PRIORITY, reloadable: true, &block)
       @registry[owner] ||= []
 

data/lib/bridgetown-core/static_file.rb

@@ -145,7 +145,7 @@ module Bridgetown
     end
 
     # Generates a relative path with the collection's directory removed when applicable
-    #   and additionally removes any multiple periods in the string.
+    # and additionally removes any multiple periods in the string.
     #
     # NOTE: `String#gsub!` removes all trailing periods (in comparison to `String#chomp!`)
     #

data/lib/bridgetown-core.rb

@@ -247,7 +247,8 @@ module Bridgetown
         )
     end
 
-    # @yieldself [Bridgetown::Configuration::ConfigurationDSL]
+    # @yieldparam config [Bridgetown::Configuration::ConfigurationDSL]
+    # @yieldreceiver [Bridgetown::Configuration::ConfigurationDSL]
     def configure(&)
       initializer(:init, &)
     end
@@ -300,7 +301,6 @@ module Bridgetown
     # Set the TZ environment variable to use the timezone specified
     #
     # @param timezone [String] the IANA Time Zone
-    #
     # @return [void]
     # rubocop:disable Naming/AccessorMethodName
     def set_timezone(timezone)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bridgetown-core
 version: !ruby/object:Gem::Version
-  version: 2.1.0.beta3
+  version: 2.1.0
 platform: ruby
 authors:
 - Bridgetown Team
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.1.0.beta3
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.1.0.beta3
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement