Class: VersionedDocumentation

Inherits:
Object
  • Object
show all
Defined in:
lib/ratatui_ruby/devtools/tasks/website/versioned_documentation.rb

Overview

Builds documentation for a single version.

Multi-version sites need docs generated from each git ref. Building locally would pollute the working directory. Using git checkout would disrupt work in progress.

This class extracts source files to a temp directory and runs RDoc. It copies the output to the target path. It preserves the current working directory.

Use it to build one version’s documentation within a multi-version site.

Instance Method Summary collapse

Constructor Details

#initialize(version) ⇒ VersionedDocumentation

Creates a VersionedDocumentation builder.

version

Version object to build docs for.



25
26
27
 
# File 'lib/ratatui_ruby/devtools/tasks/website/versioned_documentation.rb', line 25

def initialize(version)
  @version = version
end

Instance Method Details

#publish_to(path, project_name:, globs:, assets: []) ⇒ Object

Generates and publishes documentation for this version.

Extracts source to a temp directory, runs RDoc, and copies output. Falls back to direct RDoc if rake fails.

path

Output directory for generated docs.

project_name

Project name for RDoc title.

globs

File patterns to document.

assets

Optional directories to copy into output.



38
39
40
41
42
43
44
45
46
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/ratatui_ruby/devtools/tasks/website/versioned_documentation.rb', line 38

def publish_to(path, project_name:, globs:, assets: [])
  puts "Building documentation for #{@version.name}..."

  absolute_path = File.absolute_path(path)
  gemfile_path = File.absolute_path("Gemfile")
  custom_css_path = File.absolute_path("doc/custom.css")
  rakefile_path = File.absolute_path("Rakefile")
  tasks_dir_path = File.absolute_path("tasks")

  @version.checkout(globs:) do |source_path|
    # Copy current Rakefile and tasks into the temp directory
    # This ensures all versions use the latest example generation logic
    FileUtils.cp(rakefile_path, File.join(source_path, "Rakefile"))
    FileUtils.cp_r(tasks_dir_path, File.join(source_path, "tasks"))

    Dir.chdir(source_path) do
      title = "#{project_name} #{@version.name}"
      title = "#{project_name} (trunk)" if @version.edge?

      # Use rake rerdoc to ensure copy_examples runs
      # Set environment variables to override rdoc settings
      success = system(
        {
          "BUNDLE_GEMFILE" => gemfile_path,
          "RDOC_OUTPUT" => absolute_path,
          "RDOC_TITLE" => title,
          "RDOC_CUSTOM_CSS" => custom_css_path,
        },
        "bundle exec rake rerdoc"
      )

      # Fall back to direct rdoc call if rake fails for any reason
      unless success
        puts "  Rake task failed, falling back to direct rdoc call..."
        files = globs.flat_map { |glob| Dir[glob] }.uniq
        system(
          { "BUNDLE_GEMFILE" => gemfile_path },
          "bundle exec rdoc -o #{absolute_path} --main #{RDocConfig::MAIN} --title '#{title}' --template-stylesheets \"#{custom_css_path}\" #{files.join(' ')}"
        )
      end

      # Copy generated documentation to target path if it was generated elsewhere
      # This handles cases where RDOC_OUTPUT wasn't respected (evaluated at load time)
      temp_output_paths = ["tmp/rdoc", "doc"]
      temp_output_paths.each do |temp_path|
        # Check if this looks like generated rdoc (has index.html)
        if Dir.exist?(temp_path) && !Dir.empty?(temp_path) && File.exist?(File.join(temp_path, "index.html"))
          puts "  Copying generated docs from #{temp_path} to #{absolute_path}..."
          FileUtils.mkdir_p(absolute_path)
          FileUtils.cp_r Dir["#{temp_path}/*"], absolute_path
          break
        end
      end

      copy_assets_to(absolute_path, assets)
    end
  end
end