Module: Yard::Yaml::Discovery

Defined in:
lib/yard/yaml/discovery.rb

Overview

Discovery helpers to find YAML files and collect converted pages.

Phase 3 scope:

  • Discover files via include/exclude globs from config.
  • Convert files via Converter and return normalized page hashes.
  • Errors are handled by Converter according to config.strict.

Class Method Summary collapse

Class Method Details

.collect(config = Yard::Yaml.config) ⇒ Array<Hash>

Collect pages by converting discovered files.

Parameters:

Returns:

  • (Array<Hash>) —

    Array of page hashes: { path:, html:, title:, description:, meta: }



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/yard/yaml/discovery.rb', line 47

def collect(config = Yard::Yaml.config)
  files = find_files(config.include, config.exclude)
  results = []

  files.each do |path|
    converted = Yard::Yaml::Converter.from_file(path, {}, config: config)
    results << {
      path: path,
      html: converted[:html],
      title: converted[:title],
      description: converted[:description],
      meta: converted[:meta] || {},
    }
  rescue Yard::Yaml::Error
    # In strict mode Converter will raise; re-raise to fail the build
    raise
  rescue StandardError => e
    # Non-strict converter errors are already warned; skip file
    warn_fallback("skipping #{path}: #{e.class}: #{e.message}")
  end

  # Deterministic ordering by nav_order (if present) then title then path.
  # nav_order values sort numerically; missing/non-numeric values are treated as Infinity (i.e., after any numeric ones).
  results.sort_by { |h| [nav_order_value(h[:meta]), h[:title].to_s.downcase, h[:path]] }
end

.find_files(include_globs, exclude_globs) ⇒ Array<String>

Find YAML files using include and exclude patterns.
Patterns are evaluated relative to the current working directory.

Parameters:

  • include_globs (Array<String>)
  • exclude_globs (Array<String>)

Returns:

  • (Array<String>) —

    sorted list of file paths



19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/yard/yaml/discovery.rb', line 19

def find_files(include_globs, exclude_globs)
  incs = Array(include_globs).compact
  excs = Array(exclude_globs).compact

  files = []
  incs.each do |glob|
    next if glob.nil? || glob.to_s.strip.empty?
    Dir.glob(glob.to_s, File::FNM_CASEFOLD | File::FNM_EXTGLOB | File::FNM_PATHNAME).each do |path|
      next unless File.file?(path)
      files << path
    end
  end

  files.uniq!

  unless excs.empty?
    files.select! do |path|
      excs.none? { |pat| File.fnmatch?(pat.to_s, path, File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_CASEFOLD) }
    end
  end

  files.sort.map { |p| File.expand_path(p) }
end