class Jazzy::Config

rubocop:disable Metrics/ClassLength

Constants

BUILTIN_THEMES
BUILTIN_THEME_DIR
MERGE_MODULES
SOURCE_HOSTS
SWIFT_BUILD_TOOLS

Attributes

all_config_attrs[R]
instance[W]
base_path[RW]
module_configs[R]

Module Configs

The user can enter module information in three different ways. This consolidates them into one view for the rest of the code.

1) Single module, back-compatible

--module Foo etc etc (or not given at all)

2) Multiple modules, simple, sharing build params

--modules Foo,Bar,Baz --source-directory Xyz

3) Multiple modules, custom, different build params but

inheriting others from the top level.
This is config-file only.
- modules
  - module: Foo
    source_directory: Xyz
    build_tool_arguments: [a, b, c]

After this we’re left with ‘config.module_configs` that is an array of `Config` objects.

module_names[R]

Public Class Methods

alias_config_attr(name, forward, **opts) click to toggle source
# File lib/jazzy/config.rb, line 87
def self.alias_config_attr(name, forward, **opts)
  alias_method name.to_s, forward.to_s
  alias_method "#{name}=", "#{forward}="
  alias_method "#{name}_configured", "#{forward}_configured"
  alias_method "#{name}_configured=", "#{forward}_configured="
  @all_config_attrs << Attribute.new(name, **opts)
end
config_attr(name, **opts) click to toggle source

rubocop:enable Naming/AccessorMethodName

# File lib/jazzy/config.rb, line 79
def self.config_attr(name, **opts)
  attr_accessor name
  attr_accessor "#{name}_configured"

  @all_config_attrs ||= []
  @all_config_attrs << Attribute.new(name, **opts)
end
instance() click to toggle source

@return [Config] the current config instance creating one if needed.

# File lib/jazzy/config.rb, line 818
def self.instance
  @instance ||= new
end
new() click to toggle source

rubocop:enable Layout/ArgumentAlignment

# File lib/jazzy/config.rb, line 538
def initialize
  self.class.all_config_attrs.each do |attr|
    attr.set_to_default(self)
  end
end
parse!() click to toggle source
# File lib/jazzy/config.rb, line 549
def self.parse!
  config = new
  config.parse_command_line
  config.parse_config_file
  PodspecDocumenter.apply_config_defaults(config.podspec, config)

  config.set_module_configs

  config.validate

  config
end

Public Instance Methods

expand_glob_path(path) click to toggle source
# File lib/jazzy/config.rb, line 101
def expand_glob_path(path)
  Pathname(path).expand_path(base_path) # nil means Pathname.pwd
end
expand_path(path) click to toggle source
# File lib/jazzy/config.rb, line 105
def expand_path(path)
  abs_path = expand_glob_path(path)
  Pathname(Dir[abs_path][0] || abs_path) # Use existing filesystem spelling
end
grouped_attributes() { |attrs| ... } click to toggle source

Find keyed versions of the attributes, by config file key and then name-in-code Optional block allows filtering/overriding of attribute list.

# File lib/jazzy/config.rb, line 635
def grouped_attributes
  attrs = self.class.all_config_attrs
  attrs = yield attrs if block_given?
  %i[config_file_key name].map do |property|
    attrs.group_by(&property)
  end
end
hide_objc?() click to toggle source
# File lib/jazzy/config.rb, line 114
def hide_objc?
  hide_declarations == 'objc'
end
hide_swift?() click to toggle source
# File lib/jazzy/config.rb, line 110
def hide_swift?
  hide_declarations == 'swift'
end
locate_config_file() click to toggle source
# File lib/jazzy/config.rb, line 744
def locate_config_file
  return config_file if config_file

  source_directory.ascend do |dir|
    candidate = dir.join('.jazzy.yaml')
    return candidate if candidate.exist?
  end
  nil
end
module_name?(name) click to toggle source
# File lib/jazzy/config.rb, line 705
def module_name?(name)
  @module_names_set.include?(name)
end
module_name_known?() click to toggle source

For podspec query

# File lib/jazzy/config.rb, line 740
def module_name_known?
  module_name_configured || modules_configured
end
multiple_modules?() click to toggle source
# File lib/jazzy/config.rb, line 709
def multiple_modules?
  @module_names.count > 1
end
parse_command_line() click to toggle source

rubocop:disable Metrics/MethodLength

# File lib/jazzy/config.rb, line 567
def parse_command_line
  OptionParser.new do |opt|
    opt.banner = 'Usage: jazzy'
    opt.separator ''
    opt.separator 'Options'

    self.class.all_config_attrs.each do |attr|
      attr.attach_to_option_parser(self, opt)
    end

    opt.on('-v', '--version', 'Print version number') do
      puts "jazzy version: #{Jazzy::VERSION}"
      exit
    end

    opt.on('-h', '--help [TOPIC]', 'Available topics:',
           '  usage   Command line options (this help message)',
           '  config  Configuration file options',
           '...or an option keyword, e.g. "dash"') do |topic|
      case topic
      when 'usage', nil
        puts opt
      when 'config'
        print_config_file_help
      else
        print_option_help(topic)
      end
      exit
    end
  end.parse!

  unless ARGV.empty?
    warning "Leftover unused command-line text: #{ARGV}"
  end
end
parse_config_file() click to toggle source
# File lib/jazzy/config.rb, line 603
def parse_config_file
  config_path = locate_config_file
  return unless config_path

  self.base_path = config_path.parent

  puts "Using config file #{config_path}"
  config_file = read_config_file(config_path)

  attrs_by_conf_key, attrs_by_name = grouped_attributes

  parse_config_hash(config_file, attrs_by_conf_key, attrs_by_name)
end
parse_config_hash(hash, attrs_by_conf_key, attrs_by_name, override: false) click to toggle source
# File lib/jazzy/config.rb, line 617
def parse_config_hash(hash, attrs_by_conf_key, attrs_by_name, override: false)
  hash.each do |key, value|
    unless attr = attrs_by_conf_key[key]
      message = "Unknown config file attribute #{key.inspect}"
      if matching_name = attrs_by_name[key]
        message +=
          " (Did you mean #{matching_name.first.config_file_key.inspect}?)"
      end
      warning message
      next
    end
    setter = override ? :set : :set_if_unconfigured
    attr.first.method(setter).call(self, value)
  end
end
parse_module_configs() click to toggle source
# File lib/jazzy/config.rb, line 713
def parse_module_configs
  return [self] unless modules_configured

  raise 'Config file key `modules` must be an array' unless modules.is_a?(Array)

  if modules.first.is_a?(String)
    # Massage format (2) into (3)
    self.modules = modules.map { |mod| { 'module' => mod } }
  end

  # Allow per-module overrides of only some config options
  attrs_by_conf_key, attrs_by_name =
    grouped_attributes { |attr| attr.select(&:per_module) }

  modules.map do |module_hash|
    mod_name = module_hash['module'] || ''
    raise 'Missing `modules.module` config key' if mod_name.empty?

    dup.tap do |module_config|
      module_config.parse_config_hash(
        module_hash, attrs_by_conf_key, attrs_by_name, override: true
      )
    end
  end
end
print_attr_description(attr) click to toggle source
print_config_file_help() click to toggle source
print_option_help(topic = '') click to toggle source
read_config_file(file) click to toggle source
# File lib/jazzy/config.rb, line 754
def read_config_file(file)
  case File.extname(file)
    when '.json'
      JSON.parse(File.read(file))
    when '.yaml', '.yml'
      YAML.safe_load(File.read(file))
    else raise "Config file must be .yaml or .json, but got #{file.inspect}"
  end
end
set_module_configs() click to toggle source
# File lib/jazzy/config.rb, line 699
def set_module_configs
  @module_configs = parse_module_configs
  @module_names = module_configs.map(&:module_name)
  @module_names_set = Set.new(module_names)
end
theme_directory=(theme_directory) click to toggle source
# File lib/jazzy/config.rb, line 544
def theme_directory=(theme_directory)
  @theme_directory = theme_directory
  Doc.template_path = theme_directory + 'templates'
end
validate() click to toggle source
# File lib/jazzy/config.rb, line 643
def validate
  if source_host_configured &&
     source_host_url.nil? &&
     source_host_files_url.nil?
    warning 'Option `source_host` is set but has no effect without either ' \
      '`source_host_url` or `source_host_files_url`.'
  end

  if modules_configured && module_name_configured
    raise 'Options `modules` and `module` are both set which is not supported. ' \
      'To document multiple modules, use just `modules`.'
  end

  if modules_configured && podspec_configured
    raise 'Options `modules` and `podspec` are both set which is not supported.'
  end

  module_configs.each(&:validate_module)
end
validate_module() click to toggle source
# File lib/jazzy/config.rb, line 663
def validate_module
  if objc_mode &&
     build_tool_arguments_configured &&
     (framework_root_configured || umbrella_header_configured)
    warning 'Option `build_tool_arguments` is set: values passed to ' \
      '`framework_root` or `umbrella_header` may be ignored.'
  end
end
warning(message) click to toggle source
# File lib/jazzy/config.rb, line 562
def warning(message)
  warn "WARNING: #{message}"
end