jekyll-docs 3.6.0 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f708b326481792e17dd24c606c6ffb1467b7c7d
-  data.tar.gz: 223f0f568cf858965f2112b68441c916bd4fd3ff
+  metadata.gz: 67ece4fe4f1363dd4868a123b407c88643e0dea9
+  data.tar.gz: b2abb678aa9cf401640d2216b45b2a8e9fdf8586
 SHA512:
-  metadata.gz: b29ca9f2bc658c4b070662238f4e8987183d58837af1c3e521382253dfe7657657802f7270fd3f5ed8fd689555b1b6535358201803341af036557cadfc4c45b5
-  data.tar.gz: 007aa7d79069b6f21843e51798014d6f522ad8f2747557c50cab0c02ea959f05b5a19ef1845eb271f4ffcc0e442efee1d7091187ef52ee5ab608e399de477826
+  metadata.gz: d176d534a005962681c3e541f5934c8dbd3517826c1cc7d18d84a3f5820111c2239c16650afc998f2d9f9148e5212cf7107e31504e4fc9c5d339c4a008c0299e
+  data.tar.gz: 68f42fc5ee357a010a42957750432782cadd9645471ebf69f1aaa977e7e785f2431a87df7bdbca48db672bb5eb48505309853cd44bc851e890a082cad1c7beb6

data/lib/jekyll.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift __dir__ # For use/testing when no gem is installed
+
+# Require all of the Ruby files in the given directory.
+#
+# path - The String relative path from here to the directory.
+#
+# Returns nothing.
+def require_all(path)
+  glob = File.join(__dir__, path, "*.rb")
+  Dir[glob].sort.each do |f|
+    require f
+  end
+end
+
+# rubygems
+require "rubygems"
+
+# stdlib
+require "pathutil"
+require "forwardable"
+require "fileutils"
+require "time"
+require "English"
+require "pathname"
+require "logger"
+require "set"
+
+# 3rd party
+require "safe_yaml/load"
+require "liquid"
+require "kramdown"
+require "colorator"
+
+SafeYAML::OPTIONS[:suppress_warnings] = true
+
+module Jekyll
+  # internal requires
+  autoload :Cleaner,             "jekyll/cleaner"
+  autoload :Collection,          "jekyll/collection"
+  autoload :Configuration,       "jekyll/configuration"
+  autoload :Convertible,         "jekyll/convertible"
+  autoload :Deprecator,          "jekyll/deprecator"
+  autoload :Document,            "jekyll/document"
+  autoload :EntryFilter,         "jekyll/entry_filter"
+  autoload :Errors,              "jekyll/errors"
+  autoload :Excerpt,             "jekyll/excerpt"
+  autoload :External,            "jekyll/external"
+  autoload :FrontmatterDefaults, "jekyll/frontmatter_defaults"
+  autoload :Hooks,               "jekyll/hooks"
+  autoload :Layout,              "jekyll/layout"
+  autoload :CollectionReader,    "jekyll/readers/collection_reader"
+  autoload :DataReader,          "jekyll/readers/data_reader"
+  autoload :LayoutReader,        "jekyll/readers/layout_reader"
+  autoload :PostReader,          "jekyll/readers/post_reader"
+  autoload :PageReader,          "jekyll/readers/page_reader"
+  autoload :StaticFileReader,    "jekyll/readers/static_file_reader"
+  autoload :ThemeAssetsReader,   "jekyll/readers/theme_assets_reader"
+  autoload :LogAdapter,          "jekyll/log_adapter"
+  autoload :Page,                "jekyll/page"
+  autoload :PluginManager,       "jekyll/plugin_manager"
+  autoload :Publisher,           "jekyll/publisher"
+  autoload :Reader,              "jekyll/reader"
+  autoload :Regenerator,         "jekyll/regenerator"
+  autoload :RelatedPosts,        "jekyll/related_posts"
+  autoload :Renderer,            "jekyll/renderer"
+  autoload :LiquidRenderer,      "jekyll/liquid_renderer"
+  autoload :Site,                "jekyll/site"
+  autoload :StaticFile,          "jekyll/static_file"
+  autoload :Stevenson,           "jekyll/stevenson"
+  autoload :Theme,               "jekyll/theme"
+  autoload :ThemeBuilder,        "jekyll/theme_builder"
+  autoload :URL,                 "jekyll/url"
+  autoload :Utils,               "jekyll/utils"
+  autoload :VERSION,             "jekyll/version"
+
+  # extensions
+  require "jekyll/plugin"
+  require "jekyll/converter"
+  require "jekyll/generator"
+  require "jekyll/command"
+  require "jekyll/liquid_extensions"
+  require "jekyll/filters"
+
+  class << self
+    # Public: Tells you which Jekyll environment you are building in so you can skip tasks
+    # if you need to.  This is useful when doing expensive compression tasks on css and
+    # images and allows you to skip that when working in development.
+
+    def env
+      ENV["JEKYLL_ENV"] || "development"
+    end
+
+    # Public: Generate a Jekyll configuration Hash by merging the default
+    # options with anything in _config.yml, and adding the given options on top.
+    #
+    # override - A Hash of config directives that override any options in both
+    #            the defaults and the config file.
+    #            See Jekyll::Configuration::DEFAULTS for a
+    #            list of option names and their defaults.
+    #
+    # Returns the final configuration Hash.
+    def configuration(override = {})
+      config = Configuration.new
+      override = Configuration[override].stringify_keys
+      unless override.delete("skip_config_files")
+        config = config.read_config_files(config.config_files(override))
+      end
+
+      # Merge DEFAULTS < _config.yml < override
+      Configuration.from(Utils.deep_merge_hashes(config, override)).tap do |obj|
+        set_timezone(obj["timezone"]) if obj["timezone"]
+      end
+    end
+
+    # Public: Set the TZ environment variable to use the timezone specified
+    #
+    # timezone - the IANA Time Zone
+    #
+    # Returns nothing
+    # rubocop:disable Naming/AccessorMethodName
+    def set_timezone(timezone)
+      ENV["TZ"] = if Utils::Platforms.really_windows?
+                    Utils::WinTZ.calculate(timezone)
+                  else
+                    timezone
+                  end
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    # Public: Fetch the logger instance for this Jekyll process.
+    #
+    # Returns the LogAdapter instance.
+    def logger
+      @logger ||= LogAdapter.new(Stevenson.new, (ENV["JEKYLL_LOG_LEVEL"] || :info).to_sym)
+    end
+
+    # Public: Set the log writer.
+    #         New log writer must respond to the same methods
+    #         as Ruby's interal Logger.
+    #
+    # writer - the new Logger-compatible log transport
+    #
+    # Returns the new logger.
+    def logger=(writer)
+      @logger = LogAdapter.new(writer, (ENV["JEKYLL_LOG_LEVEL"] || :info).to_sym)
+    end
+
+    # Public: An array of sites
+    #
+    # Returns the Jekyll sites created.
+    def sites
+      @sites ||= []
+    end
+
+    # Public: Ensures the questionable path is prefixed with the base directory
+    #         and prepends the questionable path with the base directory if false.
+    #
+    # base_directory - the directory with which to prefix the questionable path
+    # questionable_path - the path we're unsure about, and want prefixed
+    #
+    # Returns the sanitized path.
+    def sanitized_path(base_directory, questionable_path)
+      return base_directory if base_directory.eql?(questionable_path)
+
+      clean_path = questionable_path.dup
+      clean_path.insert(0, "/") if clean_path.start_with?("~")
+      clean_path = File.expand_path(clean_path, "/")
+
+      return clean_path if clean_path.eql?(base_directory)
+
+      if clean_path.start_with?(base_directory.sub(%r!\z!, "/"))
+        clean_path
+      else
+        clean_path.sub!(%r!\A\w:/!, "/")
+        File.join(base_directory, clean_path)
+      end
+    end
+
+    # Conditional optimizations
+    Jekyll::External.require_if_present("liquid-c")
+  end
+end
+
+require "jekyll/drops/drop"
+require "jekyll/drops/document_drop"
+require_all "jekyll/commands"
+require_all "jekyll/converters"
+require_all "jekyll/converters/markdown"
+require_all "jekyll/drops"
+require_all "jekyll/generators"
+require_all "jekyll/tags"
+
+require "jekyll-sass-converter"

data/lib/jekyll/cleaner.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Jekyll
+  # Handles the cleanup of a site's destination before it is built.
+  class Cleaner
+    HIDDEN_FILE_REGEX = %r!\/\.{1,2}$!
+    attr_reader :site
+
+    def initialize(site)
+      @site = site
+    end
+
+    # Cleans up the site's destination directory
+    def cleanup!
+      FileUtils.rm_rf(obsolete_files)
+      FileUtils.rm_rf(metadata_file) unless @site.incremental?
+    end
+
+    private
+
+    # Private: The list of files and directories to be deleted during cleanup process
+    #
+    # Returns an Array of the file and directory paths
+    def obsolete_files
+      (existing_files - new_files - new_dirs + replaced_files).to_a
+    end
+
+    # Private: The metadata file storing dependency tree and build history
+    #
+    # Returns an Array with the metdata file as the only item
+    def metadata_file
+      [site.regenerator.metadata_file]
+    end
+
+    # Private: The list of existing files, apart from those included in
+    # keep_files and hidden files.
+    #
+    # Returns a Set with the file paths
+    def existing_files
+      files = Set.new
+      regex = keep_file_regex
+      dirs = keep_dirs
+
+      Utils.safe_glob(site.in_dest_dir, ["**", "*"], File::FNM_DOTMATCH).each do |file|
+        next if file =~ HIDDEN_FILE_REGEX || file =~ regex || dirs.include?(file)
+        files << file
+      end
+
+      files
+    end
+
+    # Private: The list of files to be created when site is built.
+    #
+    # Returns a Set with the file paths
+    def new_files
+      files = Set.new
+      site.each_site_file { |item| files << item.destination(site.dest) }
+      files
+    end
+
+    # Private: The list of directories to be created when site is built.
+    # These are the parent directories of the files in #new_files.
+    #
+    # Returns a Set with the directory paths
+    def new_dirs
+      new_files.map { |file| parent_dirs(file) }.flatten.to_set
+    end
+
+    # Private: The list of parent directories of a given file
+    #
+    # Returns an Array with the directory paths
+    def parent_dirs(file)
+      parent_dir = File.dirname(file)
+      if parent_dir == site.dest
+        []
+      else
+        [parent_dir] + parent_dirs(parent_dir)
+      end
+    end
+
+    # Private: The list of existing files that will be replaced by a directory
+    # during build
+    #
+    # Returns a Set with the file paths
+    def replaced_files
+      new_dirs.select { |dir| File.file?(dir) }.to_set
+    end
+
+    # Private: The list of directories that need to be kept because they are
+    # parent directories of files specified in keep_files
+    #
+    # Returns a Set with the directory paths
+    def keep_dirs
+      site.keep_files.map { |file| parent_dirs(site.in_dest_dir(file)) }.flatten.to_set
+    end
+
+    # Private: Creates a regular expression from the config's keep_files array
+    #
+    # Examples
+    #   ['.git','.svn'] with site.dest "/myblog/_site" creates
+    #   the following regex: /\A\/myblog\/_site\/(\.git|\/.svn)/
+    #
+    # Returns the regular expression
+    def keep_file_regex
+      %r!\A#{Regexp.quote(site.dest)}\/(#{Regexp.union(site.keep_files).source})!
+    end
+  end
+end

data/lib/jekyll/collection.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Collection
+    attr_reader :site, :label, :metadata
+    attr_writer :docs
+
+    # Create a new Collection.
+    #
+    # site - the site to which this collection belongs.
+    # label - the name of the collection
+    #
+    # Returns nothing.
+    def initialize(site, label)
+      @site     = site
+      @label    = sanitize_label(label)
+      @metadata = extract_metadata
+    end
+
+    # Fetch the Documents in this collection.
+    # Defaults to an empty array if no documents have been read in.
+    #
+    # Returns an array of Jekyll::Document objects.
+    def docs
+      @docs ||= []
+    end
+
+    # Override of normal respond_to? to match method_missing's logic for
+    # looking in @data.
+    def respond_to_missing?(method, include_private = false)
+      docs.respond_to?(method.to_sym, include_private) || super
+    end
+
+    # Override of method_missing to check in @data for the key.
+    def method_missing(method, *args, &blck)
+      if docs.respond_to?(method.to_sym)
+        Jekyll.logger.warn "Deprecation:",
+          "#{label}.#{method} should be changed to #{label}.docs.#{method}."
+        Jekyll.logger.warn "", "Called by #{caller(0..0)}."
+        docs.public_send(method.to_sym, *args, &blck)
+      else
+        super
+      end
+    end
+
+    # Fetch the static files in this collection.
+    # Defaults to an empty array if no static files have been read in.
+    #
+    # Returns an array of Jekyll::StaticFile objects.
+    def files
+      @files ||= []
+    end
+
+    # Read the allowed documents into the collection's array of docs.
+    #
+    # Returns the sorted array of docs.
+    def read
+      filtered_entries.each do |file_path|
+        full_path = collection_dir(file_path)
+        next if File.directory?(full_path)
+        if Utils.has_yaml_header? full_path
+          read_document(full_path)
+        else
+          read_static_file(file_path, full_path)
+        end
+      end
+      docs.sort!
+    end
+
+    # All the entries in this collection.
+    #
+    # Returns an Array of file paths to the documents in this collection
+    #   relative to the collection's directory
+    def entries
+      return [] unless exists?
+      @entries ||=
+        Utils.safe_glob(collection_dir, ["**", "*"], File::FNM_DOTMATCH).map do |entry|
+          entry["#{collection_dir}/"] = ""
+          entry
+        end
+    end
+
+    # Filtered version of the entries in this collection.
+    # See `Jekyll::EntryFilter#filter` for more information.
+    #
+    # Returns a list of filtered entry paths.
+    def filtered_entries
+      return [] unless exists?
+      @filtered_entries ||=
+        Dir.chdir(directory) do
+          entry_filter.filter(entries).reject do |f|
+            path = collection_dir(f)
+            File.directory?(path) || entry_filter.symlink?(f)
+          end
+        end
+    end
+
+    # The directory for this Collection, relative to the site source.
+    #
+    # Returns a String containing the directory name where the collection
+    #   is stored on the filesystem.
+    def relative_directory
+      @relative_directory ||= "_#{label}"
+    end
+
+    # The full path to the directory containing the collection.
+    #
+    # Returns a String containing th directory name where the collection
+    #   is stored on the filesystem.
+    def directory
+      @directory ||= site.in_source_dir(relative_directory)
+    end
+
+    # The full path to the directory containing the collection, with
+    #   optional subpaths.
+    #
+    # *files - (optional) any other path pieces relative to the
+    #           directory to append to the path
+    #
+    # Returns a String containing th directory name where the collection
+    #   is stored on the filesystem.
+    def collection_dir(*files)
+      return directory if files.empty?
+      site.in_source_dir(relative_directory, *files)
+    end
+
+    # Checks whether the directory "exists" for this collection.
+    # The directory must exist on the filesystem and must not be a symlink
+    #   if in safe mode.
+    #
+    # Returns false if the directory doesn't exist or if it's a symlink
+    #   and we're in safe mode.
+    def exists?
+      File.directory?(directory) && !entry_filter.symlink?(directory)
+    end
+
+    # The entry filter for this collection.
+    # Creates an instance of Jekyll::EntryFilter.
+    #
+    # Returns the instance of Jekyll::EntryFilter for this collection.
+    def entry_filter
+      @entry_filter ||= Jekyll::EntryFilter.new(site, relative_directory)
+    end
+
+    # An inspect string.
+    #
+    # Returns the inspect string
+    def inspect
+      "#<Jekyll::Collection @label=#{label} docs=#{docs}>"
+    end
+
+    # Produce a sanitized label name
+    # Label names may not contain anything but alphanumeric characters,
+    #   underscores, and hyphens.
+    #
+    # label - the possibly-unsafe label
+    #
+    # Returns a sanitized version of the label.
+    def sanitize_label(label)
+      label.gsub(%r![^a-z0-9_\-\.]!i, "")
+    end
+
+    # Produce a representation of this Collection for use in Liquid.
+    # Exposes two attributes:
+    #   - label
+    #   - docs
+    #
+    # Returns a representation of this collection for use in Liquid.
+    def to_liquid
+      Drops::CollectionDrop.new self
+    end
+
+    # Whether the collection's documents ought to be written as individual
+    #   files in the output.
+    #
+    # Returns true if the 'write' metadata is true, false otherwise.
+    def write?
+      !!metadata.fetch("output", false)
+    end
+
+    # The URL template to render collection's documents at.
+    #
+    # Returns the URL template to render collection's documents at.
+    def url_template
+      @url_template ||= metadata.fetch("permalink") do
+        Utils.add_permalink_suffix("/:collection/:path", site.permalink_style)
+      end
+    end
+
+    # Extract options for this collection from the site configuration.
+    #
+    # Returns the metadata for this collection
+    def extract_metadata
+      if site.config["collections"].is_a?(Hash)
+        site.config["collections"][label] || {}
+      else
+        {}
+      end
+    end
+
+    private
+
+    def read_document(full_path)
+      doc = Jekyll::Document.new(full_path, :site => site, :collection => self)
+      doc.read
+      if site.publisher.publish?(doc) || !write?
+        docs << doc
+      else
+        Jekyll.logger.debug "Skipped From Publishing:", doc.relative_path
+      end
+    end
+
+    private
+
+    def read_static_file(file_path, full_path)
+      relative_dir = Jekyll.sanitized_path(
+        relative_directory,
+        File.dirname(file_path)
+      ).chomp("/.")
+
+      files << StaticFile.new(
+        site,
+        site.source,
+        relative_dir,
+        File.basename(full_path),
+        self
+      )
+    end
+  end
+end