Module: Rakit::Docfx

Defined in:
lib/rakit/docfx.rb

Overview

Build Docfx static documentation sites from source. Used by task :docfx and tests. Contract: specs/010-docfx/contracts/ruby-api.md

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.docfx_path ⇒ Object

Returns the value of attribute docfx_path.



10
11
12
 
# File 'lib/rakit/docfx.rb', line 10

def docfx_path
  @docfx_path
end

Class Method Details

.build(source_dir:, output_dir:) ⇒ true, false

Parameters:

  • source_dir (String) —

    path to Docfx source (must exist and be a directory)

  • output_dir (String) —

    path for build output

Returns:

  • (true) —

    on success

  • (false) —

    on failure (Docfx not found, build failed, or invalid paths). Idempotent: repeated runs overwrite output_dir.



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/rakit/docfx.rb', line 20

def build(source_dir:, output_dir:)
  source_dir = ::File.expand_path(source_dir)
  output_dir = ::File.expand_path(output_dir)
  return false unless ::File.directory?(source_dir)
  return false if ::File.file?(source_dir)

  # Ensure output_dir can be created (parent writable)
  parent = ::File.dirname(output_dir)
  return false unless parent != output_dir
  begin
    FileUtils.mkdir_p(output_dir)
  rescue Errno::EACCES, Errno::EROFS, Errno::EEXIST, Errno::ENOTDIR
    return false
  end

  bin = docfx_path
  resolved = ::File.absolute_path?(bin) && ::File.executable?(bin) ? bin : which(bin)
  return false unless resolved
  bin = resolved

  out_abs = output_dir
  success = Dir.chdir(source_dir) do
    system(bin, "build", "-o", out_abs, out: $stdout, err: $stderr)
  end
  return false unless success
  return false unless ::File.directory?(out_abs) && (Dir.entries(out_abs) - %w[. ..]).any?

  true
end

.serve(output_dir:, open_browser: true, port: nil) ⇒ true, false

Serve a built Docfx site with the Docfx CLI (blocks until server is stopped).

Parameters:

  • output_dir (String) —

    path to built site (e.g. artifacts/docfx)

  • open_browser (Boolean) (defaults to: true) —

    pass –open-browser to docfx serve (default true)

  • port (Integer, nil) (defaults to: nil) —

    port for docfx serve (optional; docfx default if nil)

Returns:

  • (true) —

    if docfx serve was invoked (process may still be running)

  • (false) —

    if Docfx not on PATH or output_dir missing



56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/rakit/docfx.rb', line 56

def serve(output_dir:, open_browser: true, port: nil)
  output_dir = ::File.expand_path(output_dir)
  return false unless ::File.directory?(output_dir)
  bin = docfx_path
  resolved = ::File.absolute_path?(bin) && ::File.executable?(bin) ? bin : which(bin)
  return false unless resolved
  args = [resolved, "serve", output_dir]
  args << "--open-browser" if open_browser
  args.concat(["-p", port.to_s]) if port && port.to_i.positive?
  system(*args)
end

.valid_source?(source_dir) ⇒ Boolean

Returns true if docfx.json exists under source_dir.

Parameters:

  • source_dir (String) —

    path to check

Returns:

  • (Boolean) —

    true if docfx.json exists under source_dir



70
71
72
73
74
 
# File 'lib/rakit/docfx.rb', line 70

def valid_source?(source_dir)
  dir = ::File.expand_path(source_dir)
  return false unless ::File.directory?(dir)
  ::File.file?(::File.join(dir, "docfx.json"))
end