rdoc 6.15.0 → 7.0.2

data/lib/rdoc/comment.rb

@@ -162,6 +162,12 @@ class RDoc::Comment
     self
   end
 
+  # Change normalized, when creating already normalized comment.
+
+  def normalized=(value)
+    @normalized = value
+  end
+
   ##
   # Was this text normalized?
 
@@ -223,14 +229,190 @@ class RDoc::Comment
     @format == 'tomdoc'
   end
 
-  ##
-  # Create a new parsed comment from a document
+  MULTILINE_DIRECTIVES = %w[call-seq].freeze # :nodoc:
 
-  def self.from_document(document) # :nodoc:
-    comment = RDoc::Comment.new('')
-    comment.document = document
-    comment.location = RDoc::TopLevel.new(document.file) if document.file
-    comment
-  end
+  # There are more, but already handled by RDoc::Parser::C
+  COLON_LESS_DIRECTIVES = %w[call-seq Document-method].freeze # :nodoc:
+
+  DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP = /\A(?<colon>\\?:|:?)(?<directive>[\w-]+):(?<param>.*)/
+
+  private_constant :MULTILINE_DIRECTIVES, :COLON_LESS_DIRECTIVES, :DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP
+
+  class << self
+
+    ##
+    # Create a new parsed comment from a document
 
+    def from_document(document) # :nodoc:
+      comment = RDoc::Comment.new('')
+      comment.document = document
+      comment.location = RDoc::TopLevel.new(document.file) if document.file
+      comment
+    end
+
+    # Parse comment, collect directives as an attribute and return [normalized_comment_text, directives_hash]
+    # This method expands include and removes everything not needed in the document text, such as
+    # private section, directive line, comment characters `# /* * */` and indent spaces.
+    #
+    # RDoc comment consists of include, directive, multiline directive, private section and comment text.
+    #
+    # Include
+    #   # :include: filename
+    #
+    # Directive
+    #   # :directive-without-value:
+    #   # :directive-with-value: value
+    #
+    # Multiline directive (only :call-seq:)
+    #   # :multiline-directive:
+    #   #   value1
+    #   #   value2
+    #
+    # Private section
+    #   #--
+    #   # private comment
+    #   #++
+
+    def parse(text, filename, line_no, type, &include_callback)
+      case type
+      when :ruby
+        text = text.gsub(/^#+/, '') if text.start_with?('#')
+        private_start_regexp = /^-{2,}$/
+        private_end_regexp = /^\+{2}$/
+        indent_regexp = /^\s*/
+      when :c
+        private_start_regexp = /^(\s*\*)?-{2,}$/
+        private_end_regexp = /^(\s*\*)?\+{2}$/
+        indent_regexp = /^\s*(\/\*+|\*)?\s*/
+        text = text.gsub(/\s*\*+\/\s*\z/, '')
+      when :simple
+        # Unlike other types, this implementation only looks for two dashes at
+        # the beginning of the line. Three or more dashes are considered to be
+        # a rule and ignored.
+        private_start_regexp = /^-{2}$/
+        private_end_regexp = /^\+{2}$/
+        indent_regexp = /^\s*/
+      end
+
+      directives = {}
+      lines = text.split("\n")
+      in_private = false
+      comment_lines = []
+      until lines.empty?
+        line = lines.shift
+        read_lines = 1
+        if in_private
+          # If `++` appears in a private section that starts with `--`, private section ends.
+          in_private = false if line.match?(private_end_regexp)
+          line_no += read_lines
+          next
+        elsif line.match?(private_start_regexp)
+          # If `--` appears in a line, private section starts.
+          in_private = true
+          line_no += read_lines
+          next
+        end
+
+        prefix = line[indent_regexp]
+        prefix_indent = ' ' * prefix.size
+        line = line.byteslice(prefix.bytesize..)
+
+        if (directive_match = DIRECTIVE_OR_ESCAPED_DIRECTIV_REGEXP.match(line))
+          colon = directive_match[:colon]
+          directive = directive_match[:directive]
+          raw_param = directive_match[:param]
+          param = raw_param.strip
+        else
+          colon = directive = raw_param = param = nil
+        end
+
+        if !directive
+          comment_lines << prefix_indent + line
+        elsif colon == '\\:'
+          # If directive is escaped, unescape it
+          comment_lines << prefix_indent + line.sub('\\:', ':')
+        elsif raw_param.start_with?(':') || (colon.empty? && !COLON_LESS_DIRECTIVES.include?(directive))
+          # Something like `:toto::` is not a directive
+          # Only few directives allows to start without a colon
+          comment_lines << prefix_indent + line
+        elsif directive == 'include'
+          filename_to_include = param
+          include_callback.call(filename_to_include, prefix_indent).lines.each { |l| comment_lines << l.chomp }
+        elsif MULTILINE_DIRECTIVES.include?(directive)
+          value_lines = take_multiline_directive_value_lines(directive, filename, line_no, lines, prefix_indent.size, indent_regexp, !param.empty?)
+          read_lines += value_lines.size
+          lines.shift(value_lines.size)
+          unless param.empty?
+            # Accept `:call-seq: first-line\n  second-line` for now
+            value_lines.unshift(param)
+          end
+          value = value_lines.join("\n")
+          directives[directive] = [value.empty? ? nil : value, line_no]
+        else
+          directives[directive] = [param.empty? ? nil : param, line_no]
+        end
+        line_no += read_lines
+      end
+
+      normalized_comment = String.new(encoding: text.encoding) << normalize_comment_lines(comment_lines).join("\n")
+      [normalized_comment, directives]
+    end
+
+    # Remove preceding indent spaces and blank lines from the comment lines
+
+    private def normalize_comment_lines(lines)
+      blank_line_regexp = /\A\s*\z/
+      lines = lines.dup
+      lines.shift while lines.first&.match?(blank_line_regexp)
+      lines.pop while lines.last&.match?(blank_line_regexp)
+
+      min_spaces = lines.map do |l|
+        l.match(/\A *(?=\S)/)&.end(0)
+      end.compact.min
+      if min_spaces && min_spaces > 0
+        lines.map { |l| l[min_spaces..] || '' }
+      else
+        lines
+      end
+    end
+
+    # Take value lines of multiline directive
+
+    private def take_multiline_directive_value_lines(directive, filename, line_no, lines, base_indent_size, indent_regexp, has_param)
+      return [] if lines.empty?
+
+      first_indent_size = lines.first.match(indent_regexp).end(0)
+
+      # Blank line or unindented line is not part of multiline-directive value
+      return [] if first_indent_size <= base_indent_size
+
+      if has_param
+        # :multiline-directive: line1
+        #   line2
+        #   line3
+        #
+        value_lines = lines.take_while do |l|
+          l.rstrip.match(indent_regexp).end(0) > base_indent_size
+        end
+        min_indent = value_lines.map { |l| l.match(indent_regexp).end(0) }.min
+        value_lines.map { |l| l[min_indent..] }
+      else
+        # Take indented lines accepting blank lines between them
+        value_lines = lines.take_while do |l|
+          l = l.rstrip
+          indent = l[indent_regexp]
+          if indent == l || indent.size >= first_indent_size
+            true
+          end
+        end
+        value_lines.map! { |l| (l[first_indent_size..] || '').chomp }
+
+        if value_lines.size != lines.size && !value_lines.last.empty?
+          warn "#{filename}:#{line_no} Multiline directive :#{directive}: should end with a blank line."
+        end
+        value_lines.pop while value_lines.last&.empty?
+        value_lines
+      end
+    end
+  end
 end

data/lib/rdoc/generator/aliki.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+##
+# Aliki theme for RDoc documentation
+#
+# Author: Stan Lo
+#
+
+class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
+  RDoc::RDoc.add_generator self
+
+  def initialize(store, options)
+    super
+    aliki_template_dir = File.expand_path(File.join(__dir__, 'template', 'aliki'))
+    @template_dir = Pathname.new(aliki_template_dir)
+  end
+
+  ##
+  # Generate documentation. Overrides Darkfish to use Aliki's own search index
+  # instead of the JsonIndex generator.
+
+  def generate
+    setup
+
+    write_style_sheet
+    generate_index
+    generate_class_files
+    generate_file_files
+    generate_table_of_contents
+    write_search_index
+
+    copy_static
+
+  rescue => e
+    debug_msg "%s: %s\n  %s" % [
+      e.class.name, e.message, e.backtrace.join("\n  ")
+    ]
+
+    raise
+  end
+
+  ##
+  # Copy only the static assets required by the Aliki theme. Unlike Darkfish we
+  # don't ship embedded fonts or image sprites, so limit the asset list to keep
+  # generated documentation lightweight.
+
+  def write_style_sheet
+    debug_msg "Copying Aliki static files"
+    options = { verbose: $DEBUG_RDOC, noop: @dry_run }
+
+    install_rdoc_static_file @template_dir + 'css/rdoc.css', "./css/rdoc.css", options
+
+    unless @options.template_stylesheets.empty?
+      FileUtils.cp @options.template_stylesheets, '.', **options
+    end
+
+    Dir[(@template_dir + 'js/**/*').to_s].each do |path|
+      next if File.directory?(path)
+      next if File.basename(path).start_with?('.')
+
+      dst = Pathname.new(path).relative_path_from(@template_dir)
+
+      install_rdoc_static_file @template_dir + path, dst, options
+    end
+  end
+
+  ##
+  # Build a search index array for Aliki's searcher.
+
+  def build_search_index
+    setup
+
+    index = []
+
+    @classes.each do |klass|
+      next unless klass.display?
+
+      index << build_class_module_entry(klass)
+
+      klass.constants.each do |const|
+        next unless const.display?
+
+        index << build_constant_entry(const, klass)
+      end
+    end
+
+    @methods.each do |method|
+      next unless method.display?
+
+      index << build_method_entry(method)
+    end
+
+    index
+  end
+
+  ##
+  # Write the search index as a JavaScript file
+  # Format: var search_data = { index: [...] }
+  #
+  # We still write to a .js instead of a .json because loading a JSON file triggers CORS check in browsers.
+  # And if we simply inspect the generated pages using file://, which is often the case due to lack of the server mode,
+  # the JSON file will be blocked by the browser.
+
+  def write_search_index
+    debug_msg "Writing Aliki search index"
+
+    index = build_search_index
+
+    FileUtils.mkdir_p 'js' unless @dry_run
+
+    search_index_path = 'js/search_data.js'
+    return if @dry_run
+
+    data = { index: index }
+    File.write search_index_path, "var search_data = #{JSON.generate(data)};"
+  end
+
+  ##
+  # Resolves a URL for use in templates. Absolute URLs are returned unchanged.
+  # Relative URLs are prefixed with rel_prefix to ensure they resolve correctly from any page.
+
+  def resolve_url(rel_prefix, url)
+    uri = URI.parse(url)
+    if uri.absolute?
+      url
+    else
+      "#{rel_prefix}/#{url}"
+    end
+  rescue URI::InvalidURIError
+    "#{rel_prefix}/#{url}"
+  end
+
+  private
+
+  def build_class_module_entry(klass)
+    type = case klass
+           when RDoc::NormalClass then 'class'
+           when RDoc::NormalModule then 'module'
+           else 'class'
+           end
+
+    entry = {
+      name: klass.name,
+      full_name: klass.full_name,
+      type: type,
+      path: klass.path
+    }
+
+    snippet = klass.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_method_entry(method)
+    type = method.singleton ? 'class_method' : 'instance_method'
+
+    entry = {
+      name: method.name,
+      full_name: method.full_name,
+      type: type,
+      path: method.path
+    }
+
+    snippet = method.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+
+  def build_constant_entry(const, parent)
+    entry = {
+      name: const.name,
+      full_name: "#{parent.full_name}::#{const.name}",
+      type: 'constant',
+      path: parent.path
+    }
+
+    snippet = const.search_snippet
+    entry[:snippet] = snippet unless snippet.empty?
+    entry
+  end
+end

data/lib/rdoc/generator/darkfish.rb

@@ -314,6 +314,8 @@ class RDoc::Generator::Darkfish
   # Generates a class file for +klass+
 
   def generate_class(klass, template_file = nil)
+    # This is used to auto-collapse Pages section on class/module pages
+    @inside_class_file = true
     current = klass
 
     template_file ||= @template_dir + 'class.rhtml'
@@ -338,6 +340,8 @@ class RDoc::Generator::Darkfish
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
       here
     end
+  ensure
+    @inside_class_file = false
   end
 
   ##
@@ -352,7 +356,9 @@ class RDoc::Generator::Darkfish
 
     current = nil
 
-    @classes.each do |klass|
+    # Document files are generated only for non-alias classes/modules
+    @classes.reject(&:is_alias_for).each do |klass|
+
       current = klass
 
       generate_class klass, template_file
@@ -764,7 +770,7 @@ class RDoc::Generator::Darkfish
   end
 
   def traverse_classes(klasses, grouped_classes, rel_prefix, solo = false)
-    content = +'<ul class="link-list">'
+    content = +'<ul class="link-list nav-list">'
 
     klasses.each do |index_klass|
       if children = grouped_classes[index_klass.full_name]

data/lib/rdoc/generator/template/aliki/_aside_toc.rhtml

@@ -0,0 +1,8 @@
+<aside class="table-of-contents" role="complementary" aria-label="Table of Contents">
+  <div class="toc-sticky">
+    <h3 class="toc-heading">On This Page</h3>
+    <nav class="toc-nav" id="toc-nav" aria-label="Page sections">
+      <!-- Generated by JavaScript based on page headings -->
+    </nav>
+  </div>
+</aside>

data/lib/rdoc/generator/template/aliki/_footer.rhtml

@@ -0,0 +1,23 @@
+<footer class="site-footer">
+  <% if @options.footer_content && !@options.footer_content.empty? %>
+  <div class="footer-content">
+    <% @options.footer_content.each do |column_title, links| %>
+    <div>
+      <h3><%= h column_title %></h3>
+      <ul>
+        <% links.each do |text, url| %>
+        <li><a href="<%= h resolve_url(rel_prefix, url) %>"><%= h text %></a></li>
+        <% end %>
+      </ul>
+    </div>
+    <% end %>
+  </div>
+  <% end %>
+
+  <div class="footer-bottom">
+    <p>
+      Generated by <a href="https://ruby.github.io/rdoc/">RDoc <%= RDoc::VERSION %></a>
+      using the Aliki theme by <a href="http://st0012.dev">Stan Lo</a>
+    </p>
+  </div>
+</footer>

data/lib/rdoc/generator/template/aliki/_head.rhtml

@@ -0,0 +1,158 @@
+<meta charset="<%= @options.charset %>">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
+<title><%= h @title %></title>
+
+<%- if defined?(klass) %>
+  <meta
+    name="keywords"
+    content="ruby,<%= h "#{klass.type},#{klass.full_name}" %>"
+  >
+  <%- if klass.comment.empty? %>
+    <meta
+      name="description"
+      content="Documentation for the <%= h "#{klass.full_name} #{klass.type}" %>"
+    >
+  <%- else %>
+    <meta
+      name="description"
+      content="<%= h "#{klass.type} #{klass.full_name}: #{excerpt(klass.comment)}" %>"
+    >
+  <%- end %>
+<%- elsif defined?(file) %>
+  <meta name="keywords" content="ruby,documentation,<%= h file.page_name %>">
+  <meta
+    name="description"
+    content="<%= h "#{file.page_name}: #{excerpt(file.comment)}" %>"
+  >
+<%- elsif @title %>
+  <meta name="keywords" content="ruby,documentation,<%= h @title %>">
+  <%- if @options.main_page and
+      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
+    <meta
+      name="description"
+      content="<%= h "#{@title}: #{excerpt(main_page.comment)}" %>"
+    >
+  <%- else %>
+    <meta name="description" content="Documentation for <%= h @title %>">
+  <%- end %>
+<%- end %>
+
+<%- if canonical_url = @options.canonical_root %>
+  <% canonical_url = current.canonical_url if defined?(current) %>
+  <link rel="canonical" href="<%= canonical_url %>">
+<%- end %>
+
+<!-- Open Graph / Facebook -->
+<meta property="og:type" content="website">
+<meta property="og:title" content="<%= h @title %>">
+
+<%- if defined?(klass) %>
+  <%- if klass.comment.empty? %>
+    <meta
+      property="og:description"
+      content="Documentation for <%= h klass.full_name %> <%= h klass.type %> - API reference and code examples"
+    >
+  <%- else %>
+    <meta property="og:description" content="<%= h excerpt(klass.comment) %>">
+  <%- end %>
+<%- elsif defined?(file) %>
+  <%- if file.comment.empty? %>
+    <meta
+      property="og:description"
+      content="<%= h file.page_name %> - <%= h @title %> documentation"
+    >
+  <%- else %>
+    <meta property="og:description" content="<%= h excerpt(file.comment) %>">
+  <%- end %>
+<%- else %>
+  <meta
+    property="og:description"
+    content="API documentation for <%= h @title %> - Browse classes, modules, and methods"
+  >
+<%- end %>
+
+<%- if canonical_url = @options.canonical_root %>
+  <% canonical_url = current.canonical_url if defined?(current) %>
+  <meta property="og:url" content="<%= canonical_url %>">
+<%- end %>
+
+<!-- Twitter -->
+<meta name="twitter:card" content="summary">
+<meta name="twitter:title" content="<%= h @title %>">
+
+<%- if defined?(klass) %>
+  <%- if klass.comment.empty? %>
+    <meta
+      name="twitter:description"
+      content="Documentation for <%= h klass.full_name %> <%= h klass.type %> - API reference and code examples"
+    >
+  <%- else %>
+    <meta name="twitter:description" content="<%= h excerpt(klass.comment) %>">
+  <%- end %>
+<%- elsif defined?(file) %>
+  <%- if file.comment.empty? %>
+    <meta
+      name="twitter:description"
+      content="<%= h file.page_name %> - <%= h @title %> documentation"
+    >
+  <%- else %>
+    <meta name="twitter:description" content="<%= h excerpt(file.comment) %>">
+  <%- end %>
+<%- else %>
+  <meta
+    name="twitter:description"
+    content="API documentation for <%= h @title %> - Browse classes, modules, and methods"
+  >
+<%- end %>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "<%= h asset_rel_prefix %>/";
+  var index_rel_prefix = "<%= h rel_prefix %>/";
+</script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/theme-toggle.js?v=<%= h RDoc::VERSION %>"
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_navigation.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_data.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_ranker.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/search_controller.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/c_highlighter.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<script
+  src="<%= h asset_rel_prefix %>/js/aliki.js?v=<%= h RDoc::VERSION %>"
+  defer
+></script>
+
+<link
+  href="<%= h asset_rel_prefix %>/css/rdoc.css?v=<%= h RDoc::VERSION %>"
+  rel="stylesheet"
+>
+
+<%- @options.template_stylesheets.each do |stylesheet| %>
+  <link
+    href="<%= h asset_rel_prefix %>/<%= h File.basename stylesheet %>?v=<%= h RDoc::VERSION %>"
+    rel="stylesheet"
+  >
+<%- end %>

data/lib/rdoc/generator/template/aliki/_header.rhtml

@@ -0,0 +1,56 @@
+<header class="top-navbar">
+  <a href="<%= rel_prefix %>/index.html" class="navbar-brand">
+    <%= h @options.title %>
+  </a>
+
+  <!-- Desktop search bar -->
+  <div class="navbar-search navbar-search-desktop" role="search">
+    <form action="#" method="get" accept-charset="utf-8">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results-desktop"
+             type="text" name="search" placeholder="Search (/) for a class, method..."
+             spellcheck="false" autocomplete="off"
+             title="Type to search, Up and Down to navigate, Enter to load">
+      <ul id="search-results-desktop" aria-label="Search Results"
+          aria-busy="false" aria-expanded="false"
+          aria-atomic="false" class="initially-hidden search-results"></ul>
+    </form>
+  </div>
+
+  <!-- Mobile search icon button -->
+  <button id="search-toggle" class="navbar-search-mobile" aria-label="Open search" type="button">
+    <span aria-hidden="true">🔍</span>
+  </button>
+
+  <!-- Theme toggle button -->
+  <button id="theme-toggle" class="theme-toggle" aria-label="Switch to dark mode" type="button">
+    <span class="theme-toggle-icon" aria-hidden="true">🌙</span>
+  </button>
+</header>
+
+<!-- Search Modal (Mobile) -->
+<div id="search-modal" class="search-modal" hidden aria-modal="true" role="dialog" aria-label="Search">
+  <div class="search-modal-backdrop"></div>
+  <div class="search-modal-content">
+    <div class="search-modal-header">
+      <form class="search-modal-form" action="#" method="get" accept-charset="utf-8">
+        <span class="search-modal-icon" aria-hidden="true">🔍</span>
+        <input id="search-field-mobile" role="combobox" aria-label="Search"
+               aria-autocomplete="list" aria-controls="search-results-mobile"
+               type="text" name="search" placeholder="Search documentation"
+               spellcheck="false" autocomplete="off">
+        <button type="button" class="search-modal-close" aria-label="Close search" id="search-modal-close">
+          <span aria-hidden="true">esc</span>
+        </button>
+      </form>
+    </div>
+    <div class="search-modal-body">
+      <ul id="search-results-mobile" aria-label="Search Results"
+          aria-busy="false" aria-expanded="false"
+          aria-atomic="false" class="search-results search-modal-results initially-hidden"></ul>
+      <div class="search-modal-empty">
+        <p>No recent searches</p>
+      </div>
+    </div>
+  </div>
+</div>