ratatui_ruby-devtools 0.2.0 → 0.3.0

data/lib/ratatui_ruby/devtools/tasks/doc_tasks.rb

@@ -0,0 +1,937 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake/tasklib"
+require "rdoc/task"
+
+require_relative "rdoc_config"
+
+class DocTasks < Rake::TaskLib # :nodoc:
+  # Custom RDoc HTML generator that captures headings for TOC
+  class CapturingToHtml < RDoc::Markup::ToHtml # :nodoc:
+    attr_reader :captured_headings
+
+    def initialize(**)
+      super
+      @captured_headings = []
+    end
+
+    def accept_heading(heading)
+      start_pos = @res.length
+      super
+      added = @res[start_pos..-1].join
+      if added =~ /id="([^"]+)"/
+        @captured_headings << { level: heading.level, text: heading.text, id: $1 }
+      end
+    end
+  end
+
+  # Create a binding context for ERB
+  class ExampleViewerContext # :nodoc:
+    attr_reader :breadcrumb_path, :page_title, :file_content_html, :file_header_html
+    attr_reader :current_file_html, :tree_data, :doc_root_link, :icons_svg, :relative_path
+    attr_reader :toc_items
+    attr_accessor :render_tree_helper
+
+    def initialize(breadcrumb_path, page_title, file_content_html, file_header_html,
+      current_file_html, tree_data, doc_root_link, icons_svg, relative_path, toc_items
+    )
+      @breadcrumb_path = breadcrumb_path
+      @page_title = page_title
+      @file_content_html = file_content_html
+      @file_header_html = file_header_html
+
+      @current_file_html = current_file_html
+      @tree_data = tree_data
+      @doc_root_link = doc_root_link
+      @icons_svg = icons_svg
+      @relative_path = relative_path
+      @toc_items = toc_items
+    end
+
+    def render_tree(tree_data, current_path, current_file_html)
+      render_tree_helper.call(tree_data, current_path, current_file_html)
+      # Output directly to preserve HTML tags
+    end
+
+    def render_toc(items)
+      return "" if items.empty?
+
+      html = []
+      html << "<ul>"
+      base_level = items.first[:level]
+
+      items.each_with_index do |item, i|
+        level = item[:level]
+        text = item[:text]
+        id = item[:id]
+
+        html << "<li><a href=\"##{id}\">#{text}</a>"
+
+        next_item = items[i + 1]
+
+        if next_item
+          next_level = next_item[:level]
+          if next_level > level
+            (next_level - level).times { html << "<ul>" }
+          elsif next_level < level
+            html << "</li>"
+            (level - next_level).times { html << "</ul></li>" }
+          else # same level
+            html << "</li>"
+          end
+        else
+          # Last item. Close everything back to start.
+          html << "</li>"
+          (level - base_level).times { html << "</ul></li>" }
+        end
+      end
+
+      html << "</ul>"
+      html.join("\n")
+    end
+
+    def get_binding
+      binding
+    end
+  end
+
+  def initialize
+    super
+    define
+  end
+
+  private def define
+    RDoc::Task.new do |rdoc|
+      rdoc.rdoc_dir = ENV["RDOC_OUTPUT"] || "tmp/rdoc"
+      rdoc.main = RDocConfig::MAIN
+      rdoc.title = ENV["RDOC_TITLE"] if ENV["RDOC_TITLE"]
+      rdoc.rdoc_files.include(RDocConfig::RDOC_FILES)
+      custom_css = ENV["RDOC_CUSTOM_CSS"] || "doc/custom.css"
+      rdoc.options << "--template-stylesheets=#{custom_css}"
+    end
+
+    # RDoc 8 renders the main page only as index.html, but still turns Markdown
+    # links to README.md into README_md.html. Redirect that page so those links,
+    # and links to it from before RDoc 8, keep working.
+    task :redirect_main_page do
+      rdoc_dir = ENV["RDOC_OUTPUT"] || "tmp/rdoc"
+      main_page = File.join(rdoc_dir, "#{RDocConfig::MAIN.tr('.', '_')}.html")
+      next if File.exist?(main_page) || !File.exist?(File.join(rdoc_dir, "index.html"))
+
+      File.write(main_page, <<~HTML)
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <title>#{RDocConfig::MAIN}</title>
+          <link rel="canonical" href="index.html">
+          <meta http-equiv="refresh" content="0; url=index.html">
+          <script>location.replace("index.html" + location.hash);</script>
+        </head>
+        <body><a href="index.html">#{RDocConfig::MAIN}</a></body>
+        </html>
+      HTML
+    end
+
+    task :copy_doc_images do
+      rdoc_dir = ENV["RDOC_OUTPUT"] || "tmp/rdoc"
+      if Dir.exist?("doc/images")
+        FileUtils.mkdir_p "#{rdoc_dir}/doc/images"
+        FileUtils.cp_r Dir["doc/images/*.png"], "#{rdoc_dir}/doc/images"
+        FileUtils.cp_r Dir["doc/images/*.gif"], "#{rdoc_dir}/doc/images"
+      end
+    end
+
+    task :copy_examples do
+      puts "Copying examples..."
+      require "erb"
+
+      require "rdoc"
+      require "rdoc/markdown"
+      require "rdoc/markup/to_html"
+
+      rdoc_dir = ENV["RDOC_OUTPUT"] || "tmp/rdoc"
+
+      if Dir.exist?("examples")
+        FileUtils.rm_rf "#{rdoc_dir}/examples"
+        FileUtils.mkdir_p "#{rdoc_dir}/examples"
+
+        all_files = Dir.glob("examples/**/*.{rb,md}")
+
+        template = File.read("tasks/example_viewer.html.erb")
+        erb = ERB.new(template)
+
+        # Find the RDoc icons template
+        icons_path = Gem.find_files("rdoc/generator/template/aliki/_icons.rhtml").first
+        icons_svg = icons_path ? File.read(icons_path) : ""
+
+        # Group files by directory
+        files_by_dir = all_files.group_by { |f| File.dirname(f) }
+
+        # Collect search index entries
+        search_entries = []
+
+        # Generate HTML files for each file
+        all_files.each do |file_path|
+          relative_path = file_path.sub("examples/", "")
+          target_dir = "#{rdoc_dir}/examples/#{File.dirname(relative_path)}"
+          FileUtils.mkdir_p target_dir
+
+          content = File.read(file_path)
+          ext = File.extname(file_path)
+          filename = File.basename(file_path)
+          toc_items = []
+
+          if ext == ".md"
+            # Markdown files usually have their own H1, so no header needed
+            page_title = filename
+            breadcrumb_path = relative_path
+            file_header_html = ""
+
+            # Parse markdown
+            doc = RDoc::Markdown.parse(content)
+
+            # Render and capture headings
+            renderer = CapturingToHtml.new
+            file_content_html = doc.accept(renderer)
+            toc_items = renderer.captured_headings
+
+            # For Markdown, if we assume the first header is the title and is already captured,
+            # we might not need to prepend anything.
+            # But if file_header_html is empty, the H1 is in file_content_html.
+            # CapturingToHtml should have captured it.
+          else
+            info = extract_rdoc_info(content, filename)
+
+            if info[:title]
+              page_title = info[:title]
+              breadcrumb_path = relative_path
+            else
+              page_title = filename
+              breadcrumb_path = "#{File.dirname(relative_path)}/"
+            end
+
+            # Add to search index
+            html_path = "#{File.dirname(relative_path)}/#{File.basename(file_path).gsub('.', '_')}.html"
+            search_entries << {
+              name: page_title,
+              full_name: relative_path,
+              type: info[:title] ? "class" : "file",
+              path: html_path,
+              snippet: info[:search_snippet],
+            }
+
+            file_header_html = "<h1 id=\"top\">#{ERB::Util.html_escape(page_title)}</h1>"
+
+            # Concatenate comment and Source Code section
+            parts = []
+            if info[:raw_comment] && !info[:raw_comment].strip.empty?
+              parts << info[:raw_comment]
+            end
+
+            indented_code = content.gsub(/^/, "  ")
+            parts << "= Source Code\n\n#{indented_code}"
+
+            combined_doc = parts.join("\n\n")
+
+            # Parse and render
+            doc = RDoc::Markup.parse(combined_doc)
+            renderer = CapturingToHtml.new
+            file_content_html = doc.accept(renderer)
+            toc_items = renderer.captured_headings
+
+            # Add Page Title to TOC
+            toc_items.unshift({ level: 1, text: page_title, id: "top" })
+          end
+
+          # Calculate link to doc root
+
+          # Calculate link to doc root
+          depth = relative_path.split("/").size - 1
+          doc_root_link = "#{'../' * (depth + 1)}index.html"
+
+          # Build tree structure for sidebar
+          current_file_html = "#{File.basename(file_path).gsub('.', '_')}.html"
+          tree_data = build_tree(all_files, "examples", nil)
+
+          context = ExampleViewerContext.new(breadcrumb_path, page_title, file_content_html, file_header_html,
+            current_file_html, tree_data, doc_root_link, icons_svg, relative_path, toc_items)
+          context.render_tree_helper = lambda { |tree, path, file|
+            render_tree_html(tree, path, file)
+          }
+          html = erb.result(context.get_binding)
+
+          html_file = "#{target_dir}/#{File.basename(file_path).gsub('.', '_')}.html"
+          File.write(html_file, html)
+        end
+
+        # Write search index for examples
+        FileUtils.mkdir_p "#{rdoc_dir}/examples/js"
+        search_data = { index: search_entries }
+        File.write("#{rdoc_dir}/examples/js/search_data.js", "var search_data = #{JSON.generate(search_data)};")
+
+        # Copy RDoc search JS files to examples
+        rdoc_js_dir = Gem.find_files("rdoc/generator/template/aliki/js").first
+        if rdoc_js_dir && Dir.exist?(rdoc_js_dir)
+          %w[search_navigation.js search_ranker.js search_controller.js aliki.js].each do |js_file|
+            src = File.join(rdoc_js_dir, js_file)
+            FileUtils.cp(src, "#{rdoc_dir}/examples/js/#{js_file}") if File.exist?(src)
+          end
+        end
+
+        # Generate index.html files for each directory
+        files_by_dir.each do |dir, files|
+          target_dir = "#{rdoc_dir}/examples/#{dir}".sub("examples/", "")
+          FileUtils.mkdir_p target_dir
+
+          # Get parent directory
+          if dir == "examples"
+            parent_link = nil
+            doc_root_link = "../index.html"
+          else
+            parent_dir = File.dirname(dir).sub("examples/", "")
+            parent_link = (parent_dir == ".") ? "../index.html" : "../index.html"
+            depth = dir.sub("examples/", "").split("/").size
+            doc_root_link = "#{'../' * (depth + 1)}index.html"
+          end
+
+          # Find subdirectories
+          subdirs = files_by_dir.keys.select { |d| File.dirname(d) == dir && d != dir }
+
+          # Build combined list of folders and files with icons
+          items = []
+          subdirs.each { |d| items << { type: :dir, name: File.basename(d), path: "#{File.basename(d)}/index.html", icon: "📁" } }
+          files.each { |f| items << { type: :file, name: File.basename(f), path: "#{File.basename(f).gsub('.', '_')}.html", icon: "📄" } }
+
+          # Sort alphabetically
+          sorted_items = items.sort_by { |i| i[:name].downcase }
+
+          index_html = <<~HTML
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+              <meta charset="UTF-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1">
+              <title>Examples</title>
+              <link href="#{doc_root_link.sub('index.html', '')}css/rdoc.css" rel="stylesheet">
+              <link href="#{doc_root_link.sub('index.html', '')}custom.css" rel="stylesheet">
+              <script>
+                var rdoc_rel_prefix = "#{doc_root_link.sub('index.html', '')}";
+              </script>
+            </head>
+            <body class="file">
+              <header class="top-navbar">
+                <div class="navbar-brand">Examples</div>
+                <div class="navbar-search navbar-search-desktop"></div>
+                <button id="theme-toggle" class="theme-toggle" aria-label="Switch to dark mode" type="button" onclick="cycleColorMode()">
+                  <span class="theme-toggle-icon" aria-hidden="true">🌙</span>
+                </button>
+              </header>
+              
+              <nav id="navigation" role="navigation">
+                <div id="fileindex-section" class="nav-section">
+                  <h3>Navigation</h3>
+                  <ul class="nav-list">
+                    <li><a href="#{doc_root_link}">← Back to Docs</a></li>
+                    #{parent_link ? "<li><a href=\"#{parent_link}\">↑ Up to parent directory</a></li>" : ''}
+                  </ul>
+                </div>
+              </nav>
+
+              <main role="main">
+                <div class="content">
+                  <ul class="file-list">
+                    #{sorted_items.map { |item| "<li><a href=\"#{item[:path]}\"><span class=\"icon\">#{item[:icon]}</span>#{item[:name]}#{(item[:type] == :dir) ? '/' : ''}</a></li>" }.join("\n              ")}
+                  </ul>
+                </div>
+                <div class="footer"><a href="#{doc_root_link}">← Back to docs</a></div>
+              </main>
+
+              <script>
+                const modes = ['auto', 'light', 'dark'];
+                const icons = { auto: '🌓', light: '☀️', dark: '🌙' };
+                
+                function setColorMode(mode) {
+                  if (mode === 'auto') {
+                    document.documentElement.removeAttribute('data-theme');
+                    const systemTheme = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light';
+                    document.documentElement.setAttribute('data-theme', systemTheme);
+                  } else {
+                    document.documentElement.setAttribute('data-theme', mode);
+                  }
+                  
+                  const icon = icons[mode];
+                  const toggle = document.getElementById('theme-toggle');
+                  if (toggle) {
+                    toggle.querySelector('.theme-toggle-icon').textContent = icon;
+                  }
+                  
+                  localStorage.setItem('rdoc-theme', mode);
+                }
+                
+                function cycleColorMode() {
+                  const current = localStorage.getItem('rdoc-theme') || 'auto';
+                  const currentIndex = modes.indexOf(current);
+                  const nextMode = modes[(currentIndex + 1) % modes.length];
+                  setColorMode(nextMode);
+                }
+                
+                const savedMode = localStorage.getItem('rdoc-theme') || 'auto';
+                setColorMode(savedMode);
+              </script>
+            </body>
+            </html>
+          HTML
+
+          File.write("#{target_dir}/index.html", index_html)
+        end
+
+        # Generate root index.html
+        root_files = all_files.select { |f| File.dirname(f) == "examples" }
+        root_subdirs = files_by_dir.keys.select { |d| File.dirname(d) == "examples" && d != "examples" }
+
+        # Build combined list of root folders and files with icons
+        root_items = []
+        root_subdirs.each { |d| root_items << { type: :dir, name: File.basename(d), path: "#{File.basename(d)}/index.html", icon: "📁" } }
+        root_files.each { |f| root_items << { type: :file, name: File.basename(f), path: "#{File.basename(f).gsub('.', '_')}.html", icon: "📄" } }
+
+        # Sort alphabetically
+        sorted_root_items = root_items.sort_by { |i| i[:name].downcase }
+
+        root_index_html = <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>Examples</title>
+            <link href="../css/rdoc.css" rel="stylesheet">
+            <link href="../custom.css" rel="stylesheet">
+            <script>
+              var rdoc_rel_prefix = "../";
+            </script>
+          </head>
+          <body class="file">
+            <header class="top-navbar">
+              <div class="navbar-brand">Examples</div>
+              <div class="navbar-search navbar-search-desktop"></div>
+              <button id="theme-toggle" class="theme-toggle" aria-label="Switch to dark mode" type="button" onclick="cycleColorMode()">
+                <span class="theme-toggle-icon" aria-hidden="true">🌙</span>
+              </button>
+            </header>
+
+            <nav id="navigation" role="navigation">
+              <div id="fileindex-section" class="nav-section">
+                <h3>Navigation</h3>
+                <ul class="nav-list">
+                  <li><a href="../index.html">← Back to Docs</a></li>
+                </ul>
+              </div>
+            </nav>
+
+            <main role="main">
+              <div class="content">
+                <ul class="file-list">
+                  #{sorted_root_items.map { |item| "<li><a href=\"#{item[:path]}\"><span class=\"icon\">#{item[:icon]}</span>#{item[:name]}#{(item[:type] == :dir) ? '/' : ''}</a></li>" }.join("\n            ")}
+                </ul>
+              </div>
+              <div class="footer"><a href="../index.html">← Back to docs</a></div>
+            </main>
+
+            <script>
+              const modes = ['auto', 'light', 'dark'];
+              const icons = { auto: '🌓', light: '☀️', dark: '🌙' };
+              
+              function setColorMode(mode) {
+                if (mode === 'auto') {
+                  document.documentElement.removeAttribute('data-theme');
+                  const systemTheme = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light';
+                  document.documentElement.setAttribute('data-theme', systemTheme);
+                } else {
+                  document.documentElement.setAttribute('data-theme', mode);
+                }
+                
+                const icon = icons[mode];
+                const toggle = document.getElementById('theme-toggle');
+                if (toggle) {
+                  toggle.querySelector('.theme-toggle-icon').textContent = icon;
+                }
+                
+                localStorage.setItem('rdoc-theme', mode);
+              }
+              
+              function cycleColorMode() {
+                const current = localStorage.getItem('rdoc-theme') || 'auto';
+                const currentIndex = modes.indexOf(current);
+                const nextMode = modes[(currentIndex + 1) % modes.length];
+                setColorMode(nextMode);
+              }
+              
+              const savedMode = localStorage.getItem('rdoc-theme') || 'auto';
+              setColorMode(savedMode);
+            </script>
+          </body>
+          </html>
+        HTML
+
+        File.write("#{rdoc_dir}/examples/index.html", root_index_html)
+      end
+    end
+
+    Rake::Task[:rdoc].enhance do
+      Rake::Task[:copy_doc_images].invoke
+      Rake::Task[:copy_examples].invoke
+      Rake::Task[:rewrite_examples_link].invoke
+      Rake::Task[:redirect_main_page].invoke
+    end
+
+    Rake::Task[:rerdoc].enhance do
+      Rake::Task[:copy_doc_images].invoke
+      Rake::Task[:copy_examples].invoke
+      Rake::Task[:rewrite_examples_link].invoke
+      Rake::Task[:redirect_main_page].invoke
+    end
+
+    task :rewrite_examples_link do
+      require "nokogiri"
+
+      rdoc_dir = ENV["RDOC_OUTPUT"] || "tmp/rdoc"
+
+      # Build a mapping of example READMEs to their H1 titles and categories
+      examples_by_category = { "Apps" => [], "Widgets" => [] }
+
+      Dir.glob("examples/*/README.md").each do |readme_path|
+        dir_name = File.dirname(readme_path).sub("examples/", "")
+
+        # Skip verify examples entirely
+        next if dir_name.start_with?("verify_")
+
+        content = File.read(readme_path)
+        if content =~ /^#\s+(.+)$/
+          title = $1.strip.sub(/ Example$/, "") # Remove trailing " Example"
+          rdoc_path = "examples/#{dir_name}/README_md.html"
+
+          # Categorize by prefix
+          category = if dir_name.start_with?("app_")
+            "Apps"
+          elsif dir_name.start_with?("widget_")
+            title = title.sub(/ Widget$/, "") # Also strip trailing " Widget" for widgets
+            "Widgets"
+          else
+            nil
+          end
+
+          if category
+            examples_by_category[category] << { title:, rdoc_path:, dir_name: }
+          end
+        end
+      end
+
+      # Sort each category alphabetically by title
+      examples_by_category.each_value { |list| list.sort_by! { |e| e[:title] } }
+
+      # Process all HTML files
+      Dir.glob("#{rdoc_dir}/**/*.html").each do |file|
+        content = File.read(file)
+        modified = false
+
+        doc = Nokogiri::HTML(content)
+
+        # Find the examples details section to remove from Pages
+        examples_detail = doc.css("details summary").find { |s| s.text.strip.downcase == "examples" }&.parent
+
+        # Find the classindex-section to insert Examples section before it
+        classindex_section = doc.at_css("#classindex-section")
+
+        if examples_detail && classindex_section
+          # Remove examples from Pages section
+          examples_detail.remove
+
+          # Build the new Examples section as a top-level nav-section
+          current_depth = file.sub("#{rdoc_dir}/", "").count("/")
+          prefix = "../" * current_depth
+
+          examples_section = Nokogiri::XML::Node.new("div", doc)
+          examples_section["id"] = "exampleindex-section"
+          examples_section["class"] = "nav-section"
+
+          examples_section.inner_html = <<~HTML
+            <details class="nav-section-collapsible" open>
+              <summary class="nav-section-header">
+                <span class="nav-section-icon">
+                  <svg><use href="#icon-layers"></use></svg>
+                </span>
+                <span class="nav-section-title">Examples</span>
+                <span class="nav-section-chevron">
+                  <svg><use href="#icon-chevron"></use></svg>
+                </span>
+              </summary>
+              <ul class="link-list nav-list">
+              </ul>
+            </details>
+          HTML
+
+          # Build the category structure
+          examples_ul = examples_section.at_css("ul.link-list")
+
+          examples_by_category.each do |category_name, examples|
+            next if examples.empty?
+
+            cat_li = Nokogiri::XML::Node.new("li", doc)
+            cat_details = Nokogiri::XML::Node.new("details", doc)
+            # Subcategories closed by default
+            cat_summary = Nokogiri::XML::Node.new("summary", doc)
+            cat_summary.content = category_name
+            cat_details.add_child(cat_summary)
+
+            cat_ul = Nokogiri::XML::Node.new("ul", doc)
+            cat_ul["class"] = "link-list nav-list"
+
+            examples.each do |example|
+              li = Nokogiri::XML::Node.new("li", doc)
+              a = Nokogiri::XML::Node.new("a", doc)
+              a["href"] = "#{prefix}#{example[:rdoc_path]}"
+              a.content = example[:title]
+              li.add_child(a)
+              cat_ul.add_child(li)
+            end
+
+            cat_details.add_child(cat_ul)
+            cat_li.add_child(cat_details)
+            examples_ul.add_child(cat_li)
+          end
+
+          # Insert Examples section before Classes and Modules
+          classindex_section.add_previous_sibling(examples_section)
+
+          # --- GUIDES SECTION ---
+          # Build dynamic hierarchical tree from doc/ folder structure
+          guides_tree = build_guides_tree
+
+          # Find and remove the doc details section from Pages
+          doc_detail = doc.css("details summary").find { |s| s.text.strip.downcase == "doc" }&.parent
+          doc_detail&.remove
+
+          # Create the Guides section
+          guides_section = Nokogiri::XML::Node.new("div", doc)
+          guides_section["id"] = "guidesindex-section"
+          guides_section["class"] = "nav-section"
+
+          guides_section.inner_html = <<~HTML
+            <details class="nav-section-collapsible" open>
+              <summary class="nav-section-header">
+                <span class="nav-section-icon">
+                  <svg><use href="#icon-file"></use></svg>
+                </span>
+                <span class="nav-section-title">Guides</span>
+                <span class="nav-section-chevron">
+                  <svg><use href="#icon-chevron"></use></svg>
+                </span>
+              </summary>
+              <ul class="link-list nav-list">
+              </ul>
+            </details>
+          HTML
+
+          # Get current file path relative to rdoc_dir (e.g. "doc/getting_started/quickstart_md.html")
+          current_file_rel = file.sub("#{rdoc_dir}/", "")
+
+          guides_ul = guides_section.at_css("ul.link-list")
+          build_guides_nav(guides_ul, guides_tree, doc, prefix, current_file_rel, "doc")
+
+          # Insert Guides section before Examples
+          examples_section.add_previous_sibling(guides_section)
+
+          content = doc.to_html
+          modified = true
+        end
+
+        # Also rewrite examples_md.html to examples/index.html
+        if content.include?("examples_md.html")
+          content = content.gsub(/href="([^"]*?)examples_md\.html"/, 'href="\1examples/index.html"')
+          modified = true
+        end
+
+        File.write(file, content) if modified
+      end
+
+      # Delete the now-unused examples_md.html
+      examples_page = "#{rdoc_dir}/examples_md.html"
+      FileUtils.rm_f(examples_page)
+
+      puts "Created Examples and Guides sections in sidebar"
+    end
+
+    namespace :doc do
+      desc "Check for broken links in RDoc and Markdown files"
+      task :check_links do
+        require_relative "doc/link_audit"
+
+        root = Dir.pwd
+
+        print "Verify HTTP/HTTPS URLs (slow)? [Y/n] "
+        $stdout.flush
+        verify_web = $stdin.gets&.strip&.downcase != "n"
+
+        audit = LinkAudit.new(root, verify_web:)
+        puts audit
+
+        exit 1 unless audit.success?
+      end
+    end
+  end
+
+  private def build_tree(all_files, root_dir, max_depth = nil, current_depth = 1)
+    return {} if max_depth && current_depth > max_depth
+
+    files_by_dir = all_files.group_by { |f| File.dirname(f) }
+    dirs_at_level = files_by_dir.keys.select { |d| d.start_with?(root_dir) && d.count("/") == current_depth }
+
+    tree = {}
+
+    dirs_at_level.each do |dir|
+      dir_name = dir.split("/").last
+      files = files_by_dir[dir] || []
+
+      tree[dir_name] = {
+        path: dir.sub("examples/", ""),
+        files: files.map { |f|
+          {
+            name: File.basename(f),
+            path: "#{File.basename(f).gsub('.', '_')}.html",
+            full_path: f,
+          }
+        }.sort_by { |f| f[:name] },
+        subdirs: build_tree(all_files, dir, max_depth, current_depth + 1),
+      }
+    end
+
+    tree
+  end
+
+  private def extract_rdoc_info(content, filename)
+    require "rdoc/comment"
+    require "rdoc/markup/to_html"
+
+    options = RDoc::Options.new
+    store = RDoc::Store.new(options)
+    top_level = store.add_file filename
+    stats = RDoc::Stats.new(store, 1)
+
+    parser = RDoc::Parser::Ruby.new(top_level, content, options, stats)
+    parser.scan
+
+    lines = content.lines
+
+    # Find the first class/module defined in the file
+    # We want the one that appears earliest in the file
+    # Filter out items with nil lines
+    target_class = top_level.classes_or_modules.select(&:line).min_by(&:line)
+
+    if target_class
+      # Use the class definition line as the anchor
+      # RDoc line numbers are 1-based
+      anchor_index = target_class.line - 1
+      title = target_class.name
+      search_snippet = target_class.respond_to?(:search_snippet) ? target_class.search_snippet : ""
+    else
+      # Fallback to first line of code if no class defined
+      first_code_index = lines.find_index { |l| !l.strip.empty? && !l.strip.start_with?("#") }
+      anchor_index = first_code_index
+      title = nil
+      search_snippet = ""
+    end
+
+    # Walk upwards from the line before the anchor to find immediate comments
+    comment_lines = []
+    if anchor_index && anchor_index > 0
+      idx = anchor_index - 1
+      while idx >= 0
+        line = lines[idx].strip
+
+        # Stop at blank lines
+        break if line.empty?
+
+        # Stop if we hit something that isn't a comment (shouldn't happen if we are above code, but safety check)
+        break unless line.start_with?("#")
+
+        comment_lines.unshift(lines[idx])
+        idx -= 1
+      end
+    end
+
+    raw_comment = nil
+    unless comment_lines.empty?
+      # Create RDoc comment from extracted lines
+      # Strip leading # and optional space
+      cleaned_lines = comment_lines.map do |line|
+        line.strip.sub(/^#\s?/, "")
+      end
+      raw_comment = cleaned_lines.join("\n")
+      # Use first line of comment as snippet if RDoc didn't provide one
+      search_snippet = cleaned_lines.first if search_snippet.empty?
+    end
+
+    {
+      title:,
+      raw_comment:,
+      search_snippet:,
+    }
+  rescue => e
+    puts "Warning: Failed to extract RDoc info for #{filename}: #{e.message}"
+    { title: nil, raw_comment: nil, search_snippet: "" }
+  end
+
+  private def render_tree_html(tree_data, current_path, current_file_html, depth = 0)
+    html_parts = []
+
+    # Calculate prefix to return to examples root from current file
+    current_depth = current_path.split("/").size - 1
+    root_prefix = "../" * current_depth
+
+    tree_data.keys.sort.each do |dir_name|
+      item = tree_data[dir_name]
+      has_children = item[:files].any? || item[:subdirs].any?
+
+      if has_children
+        # Check if this directory is in the path of the current file
+        # item[:path] is relative to examples root (e.g., "app_all_events/model")
+        # current_path is also relative to examples root (e.g., "app_all_events/model/event_color_cycle")
+        # We want to open if current_path starts with this directory's path
+        is_in_path = current_path == item[:path] || current_path.start_with?("#{item[:path]}/")
+        open_attr = is_in_path ? "open" : ""
+
+        html_parts << "<li>"
+        html_parts << "  <details #{open_attr}>"
+        html_parts << "    <summary>#{ERB::Util.html_escape(dir_name)}</summary>"
+        html_parts << "    <ul class=\"link-list nav-list\">"
+
+        # Add files
+        item[:files].each do |file|
+          # Check specific file match
+          # file[:path] is the HTML filename (e.g., "event_color_cycle.html")
+          # current_file_html is the current file's HTML name
+          is_active = is_in_path && file[:path] == current_file_html
+
+          active_class = is_active ? ' class="active"' : ""
+          file_name_display = ERB::Util.html_escape(file[:name])
+          file_name_display = "<strong>#{file_name_display}</strong>" if is_active
+
+          # Link relative to examples root
+          file_path = "#{root_prefix}#{item[:path]}/#{file[:path]}"
+          html_parts << "      <li><a href=\"#{file_path}\"#{active_class}><span class=\"file\"></span>#{file_name_display}</a></li>"
+        end
+
+        # Add subdirectories recursively
+        if item[:subdirs].any?
+          html_parts << render_tree_html(item[:subdirs], current_path, current_file_html, depth + 1)
+        end
+
+        html_parts << "    </ul>"
+        html_parts << "  </details>"
+        html_parts << "</li>"
+      end
+    end
+
+    html_parts.join("\n")
+  end
+
+  # Build a hierarchical tree structure from doc/**/*.md files
+  private def build_guides_tree
+    tree = { files: [], subdirs: {} }
+
+    Dir.glob("doc/**/*.md").each do |md_path|
+      # Skip images folder
+      next if md_path.include?("/images/")
+
+      relative = md_path.sub("doc/", "")
+      parts = relative.split("/")
+      filename = parts.pop
+
+      # Get title from H1
+      content = File.read(md_path)
+      title = if content =~ /^#\s+(.+)$/
+        $1.strip
+      else
+        filename.sub(/\.md$/, "").tr("_-", " ").split.map(&:capitalize).join(" ")
+      end
+
+      # Convert to RDoc path
+      rdoc_path = "doc/#{relative.gsub('.', '_')}.html"
+
+      # Navigate to correct position in tree
+      current = tree
+      parts.each do |dir|
+        current[:subdirs][dir] ||= { files: [], subdirs: {} }
+        current = current[:subdirs][dir]
+      end
+
+      current[:files] << { title:, rdoc_path:, filename: }
+    end
+
+    # Sort files in each level alphabetically by title
+    sort_guides_tree(tree)
+    tree
+  end
+
+  private def sort_guides_tree(node)
+    node[:files].sort_by! { |f| f[:title] }
+    node[:subdirs].each_value { |subdir| sort_guides_tree(subdir) }
+  end
+
+  # Recursively build navigation elements from the tree
+  # current_file_rel: path of current HTML file relative to rdoc_dir (e.g. "doc/getting_started/quickstart_md.html")
+  # current_tree_path: path in the tree we're building (e.g. "doc", "doc/getting_started")
+  private def build_guides_nav(parent_ul, tree, doc, prefix, current_file_rel, current_tree_path)
+    # Add files at this level first
+    tree[:files].each do |file|
+      # Check if this file is the current page
+      is_current = (file[:rdoc_path] == current_file_rel)
+
+      li = Nokogiri::XML::Node.new("li", doc)
+      a = Nokogiri::XML::Node.new("a", doc)
+      a["href"] = "#{prefix}#{file[:rdoc_path]}"
+      if is_current
+        a["class"] = "active"
+        strong = Nokogiri::XML::Node.new("strong", doc)
+        strong.content = file[:title]
+        a.add_child(strong)
+      else
+        a.content = file[:title]
+      end
+      li.add_child(a)
+      parent_ul.add_child(li)
+    end
+
+    # Add subdirectories as collapsible details
+    tree[:subdirs].each do |dir_name, subtree|
+      subdir_path = "#{current_tree_path}/#{dir_name}"
+
+      # Check if current file is inside this subdirectory
+      # current_file_rel might be "doc/getting_started/quickstart_md.html"
+      # subdir_path would be "doc/getting_started"
+      is_current_in_subdir = current_file_rel.start_with?("#{subdir_path}/")
+
+      li = Nokogiri::XML::Node.new("li", doc)
+      details = Nokogiri::XML::Node.new("details", doc)
+      # Open if current file is inside this subdir
+      details["open"] = "open" if is_current_in_subdir
+      summary = Nokogiri::XML::Node.new("summary", doc)
+      summary.content = dir_name.tr("_-", " ").split.map(&:capitalize).join(" ")
+      details.add_child(summary)
+
+      subdir_ul = Nokogiri::XML::Node.new("ul", doc)
+      subdir_ul["class"] = "link-list nav-list"
+      build_guides_nav(subdir_ul, subtree, doc, prefix, current_file_rel, subdir_path)
+
+      details.add_child(subdir_ul)
+      li.add_child(details)
+      parent_ul.add_child(li)
+    end
+  end
+end