Module: Yard::Yaml::Plugin

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

Overview

Plugin activation for yard-yaml (Phase 3: config + discovery; still no YARD registrations).

Constant Summary collapse

STATE = 
{activated: false, at_exit_installed: false}
STATE_MUTEX = 
Mutex.new

Class Method Summary collapse

Class Method Details

.__reset_state__ ⇒ Object

Test-helper: reset internal activation flag. Not part of public API; used from test teardown to avoid state leakage.



97
98
99
100
101
102
103
 
# File 'lib/yard/yaml/plugin.rb', line 97

def __reset_state__
  STATE_MUTEX.synchronize do
    STATE[:activated] = false
    STATE[:at_exit_installed] = false
  end
  nil
end

.activate(argv = nil) ⇒ void

This method returns an undefined value.

Activate the plugin.

Phase 3 behavior:

  • Parse argv for ‘–yard_yaml-*` flags and apply to configuration.

  • Run discovery to collect YAML pages and mirror to registry store.

  • Do NOT register tags, templates, or handlers yet.

Parameters:

  • argv (Array<String>, nil) (defaults to: nil) —

    optional argument vector to parse



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/yard/yaml/plugin.rb', line 28

def activate(argv = nil)
  # Parse and apply CLI overrides if provided
  begin
    overrides = Cli.parse(argv || [])
    Yard::Yaml.configure(overrides) unless overrides.empty?
  rescue StandardError
    # Parsing failures should not prevent activation in Phase 3
  end

  # Collect pages via discovery using current config
  begin
    pages = Discovery.collect(Yard::Yaml.config)
    Yard::Yaml.__set_pages__(pages)
  rescue Yard::Yaml::Error
    # strict mode surfaced an error; re-raise to fail activation/build
    raise
  rescue StandardError
    # Non-strict errors are already warned by converter/discovery
  end

  STATE_MUTEX.synchronize { STATE[:activated] = true }
  nil
end

.activated? ⇒ Boolean

Whether the plugin has been activated for the current process. Activation is explicit; requiring this file does not activate anything.

Returns:

  • (Boolean) 


15
16
17
 
# File 'lib/yard/yaml/plugin.rb', line 15

def activated?
  STATE[:activated]
end

.emit!(output_dir:) ⇒ Array<String>

Emit converted pages collected during activation.

Parameters:

  • output_dir (String) —

    YARD HTML output directory

Returns:

  • (Array<String>) 


78
79
80
81
82
83
 
# File 'lib/yard/yaml/plugin.rb', line 78

def emit!(output_dir:)
  pages = Yard::Yaml.pages
  return [] if pages.nil? || pages.empty?

  Yard::Yaml::Emitter.emit!(pages: pages, output_dir: output_dir, config: Yard::Yaml.config)
end

.install_at_exit(argv = nil) ⇒ void

This method returns an undefined value.

Install an at-exit emitter for YARD’s plugin loader. YARD loads plugins before it has generated the HTML tree, so converted YAML pages must be written after YARD finishes.

Parameters:

  • argv (Array<String>, nil) (defaults to: nil) —

    the YARD argv used to discover output



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/yard/yaml/plugin.rb', line 58

def install_at_exit(argv = nil)
  should_install = STATE_MUTEX.synchronize do
    if STATE[:at_exit_installed]
      false
    else
      STATE[:at_exit_installed] = true
    end
  end
  return unless should_install

  at_exit do
    emit!(output_dir: yard_output_dir(argv || ARGV))
  end
  nil
end

.yard_output_dir(argv) ⇒ String

Resolve YARD’s HTML output directory from argv or .yardopts.

Parameters:

  • argv (Array<String>)

Returns:

  • (String) 


89
90
91
92
93
 
# File 'lib/yard/yaml/plugin.rb', line 89

def yard_output_dir(argv)
  output_dir_from_tokens(Array(argv).map(&:to_s)) ||
    output_dir_from_tokens(yardopts_tokens) ||
    "doc"
end