rdoc 6.17.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bb82d9eff1cf5ae3ee5276c97b12d57694d28c64a70ee9f318d4468c904999e
-  data.tar.gz: f7073f27e9b4a15e3b7792f777bb8b2bc991bde74409e15cdb5bd7be1900f2db
+  metadata.gz: '09f66eb1c281e4323e70183c119a58a9c97c8fef86ba4f1ae42691d614a484be'
+  data.tar.gz: eb7605a8633beab318d2bc9ee4fb66c420397a3ab48bdd5ef8c9d4c533c12ffc
 SHA512:
-  metadata.gz: 76a11b7a7529c4b008488ba22f4aa0c8c5dd2cbfff19ec795f0fa5f16e0d7c7f4913d69c2cc11d18653f8d0a4bde559f2b2a893b9dba9d8aec34faaec557b935
-  data.tar.gz: 5af47e79dc6fde12b8aa9809a0eb845db18031a907140484ea95ef16399a592c879445b8f725ae4eabfbfe5d3250656926698fa2a35b3426605420ca9961579f
+  metadata.gz: 722cd4f102ad66df12a9db58c4807545a1d489090f7e82b9d3b84422a82975c7e20dc32c263fd6ae1c5c5421e9d65a599e1dce70431dc963991292bf328f0990
+  data.tar.gz: 328b307c3ae2fd5057e40afa1f0e72da247f455aab4427698f15d51606aa469097f4816a607a518087f8284270822d8de9b30af86720c87011e1cc78b25121b0

data/CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# Contributing to RDoc
+
+Thank you for your interest in contributing to RDoc! This document provides guidelines and instructions for contributing.
+
+## Reporting Bugs
+
+If you think you found a bug, open an issue on the [issue tracker](https://github.com/ruby/rdoc/issues) on GitHub.
+
+When reporting a bug:
+
+- Include a sample file that illustrates the problem, or link to the repository/gem associated with the bug
+- Include steps to reproduce the issue
+
+## Development Setup
+
+RDoc uses Bundler for development. To get started:
+
+```bash
+bundle install
+bundle exec rake
+```
+
+This will install dependencies and run the tests.
+
+If you're working on CSS or templates, you'll also want Node dependencies for the CSS linter:
+
+```bash
+npm install
+```
+
+If tests don't pass on the first run, check the [GitHub Actions page](https://github.com/ruby/rdoc/actions) to see if there are any known failures.
+
+**Note:** Generated parser files are committed to the repository. If you delete them (for example via `bundle exec rake clean`) or you change any `.ry`/`.kpeg` parser sources, run `bundle exec rake generate` before running tests.
+
+## Running Tests
+
+```bash
+# Run all tests (default task)
+bundle exec rake
+
+# Run unit tests only (excludes RubyGems integration)
+bundle exec rake normal_test
+
+# Run RubyGems integration tests only
+bundle exec rake rubygems_test
+
+# Verify generated parser files are current (CI check)
+bundle exec rake verify_generated
+```
+
+- **Test Framework:** [`test-unit`](https://github.com/test-unit/test-unit)
+- **Test Location:** `test/` directory
+- **Test Helper:** `test/lib/helper.rb`
+
+## Linting
+
+### RuboCop (Ruby Code)
+
+```bash
+# Check Ruby code style
+bundle exec rubocop
+
+# Auto-fix style issues
+bundle exec rubocop -A
+```
+
+### Herb Linter (ERB/RHTML Templates)
+
+```bash
+# Lint ERB template files
+npx @herb-tools/linter "**/*.rhtml"
+
+# Lint specific directory
+npx @herb-tools/linter "lib/**/*.rhtml"
+```
+
+**Template Location:** `lib/rdoc/generator/template/**/*.rhtml`
+
+### Stylelint (CSS Files)
+
+```bash
+# Lint CSS files
+npm run lint:css
+
+# Auto-fix style issues
+npm run lint:css -- --fix
+```
+
+## Parser Generation
+
+RDoc uses generated parsers for Markdown and RD formats.
+
+```bash
+# Generate all parser files from sources
+bundle exec rake generate
+
+# Remove generated parser files
+bundle exec rake clean
+
+# Verify generated files are in sync with sources (CI check)
+bundle exec rake verify_generated
+```
+
+**Source Files** (edit these):
+
+- `lib/rdoc/rd/block_parser.ry` → generates `block_parser.rb` via racc
+- `lib/rdoc/rd/inline_parser.ry` → generates `inline_parser.rb` via racc
+- `lib/rdoc/markdown.kpeg` → generates `markdown.rb` via kpeg
+- `lib/rdoc/markdown/literals.kpeg` → generates `literals.rb` via kpeg
+
+**Important:**
+
+- Generated parser files **should be committed** to the repository
+- Do not edit generated `.rb` parser files directly
+- After modifying `.ry` or `.kpeg` source files, run `bundle exec rake generate`
+- CI runs `rake verify_generated` to ensure generated files are in sync with their sources
+
+## Documentation Generation
+
+```bash
+# Generate documentation (creates _site directory)
+bundle exec rake rdoc
+
+# Force regenerate documentation
+bundle exec rake rerdoc
+
+# Show documentation coverage
+bundle exec rake rdoc:coverage
+bundle exec rake coverage
+```
+
+- **Output Directory:** `_site/` (GitHub Pages compatible)
+- **Configuration:** `.rdoc_options` and `.document`
+
+## Themes
+
+RDoc ships with two HTML themes:
+
+- **Aliki** (default) - Modern theme with improved styling and navigation
+- **Darkfish** (deprecated) - Classic theme, will be removed in v8.0
+
+New feature development should focus on the Aliki theme. Darkfish will continue to receive bug fixes but no new features.
+
+Theme templates are located at `lib/rdoc/generator/template/<theme>/`.
+
+## Project Structure
+
+```
+lib/rdoc/
+├── rdoc.rb                    # Main entry point (RDoc::RDoc class)
+├── version.rb                 # Version constant
+├── task.rb                    # Rake task integration
+├── parser/                    # Source code parsers
+│   ├── ruby.rb                # Ruby code parser
+│   ├── c.rb                   # C extension parser
+│   ├── prism_ruby.rb          # Prism-based Ruby parser
+│   └── ...
+├── generator/                 # Documentation generators
+│   ├── aliki.rb               # HTML generator (default theme)
+│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v8.0)
+│   ├── markup.rb              # Markup format generator
+│   ├── ri.rb                  # RI command generator
+│   └── template/              # ERB templates
+│       ├── aliki/             # Aliki theme (default)
+│       └── darkfish/          # Darkfish theme (deprecated)
+├── markup/                    # Markup parsing and formatting
+├── code_object/               # AST objects for documented items
+├── markdown.kpeg              # Parser source (edit this)
+├── markdown.rb                # Generated parser (do not edit)
+├── markdown/                  # Markdown parsing
+│   ├── literals.kpeg          # Parser source (edit this)
+│   └── literals.rb            # Generated parser (do not edit)
+├── rd/                        # RD format parsing
+│   ├── block_parser.ry        # Parser source (edit this)
+│   ├── block_parser.rb        # Generated parser (do not edit)
+│   ├── inline_parser.ry       # Parser source (edit this)
+│   └── inline_parser.rb       # Generated parser (do not edit)
+└── ri/                        # RI (Ruby Info) tool
+
+test/                          # Test files
+├── lib/helper.rb              # Test helpers
+└── rdoc/                      # Main test directory
+```
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We're all here to make RDoc better!

data/LEGAL.rdoc

@@ -4,6 +4,12 @@
 
 The files in this distribution are covered by the Ruby license (see LICENSE) except the features mentioned below:
 
+Aliki::
+  Aliki was written by Stan Lo and is included under the MIT license.
+
+  * lib/rdoc/generator/aliki.rb
+  * lib/rdoc/generator/template/aliki/*
+
 Darkfish::
   Darkfish was written by Michael Granger and is included under the BSD 3-Clause
   license.  Darkfish contains images from the Silk Icons set by Mark James.

data/README.md

@@ -48,7 +48,7 @@ require 'rdoc/rdoc'
 
 options = RDoc::Options.new
 options.files = ['a.rb', 'b.rb']
-options.setup_generator 'darkfish'
+options.setup_generator 'aliki'
 # see RDoc::Options
 
 rdoc = RDoc::RDoc.new
@@ -90,7 +90,24 @@ To determine how well your project is documented run `rdoc -C lib` to get a docu
 
 ## Theme Options
 
-There are a few community-maintained themes for RDoc:
+RDoc ships with two built-in themes:
+
+- **Aliki** (default) - A modern, clean theme with improved navigation and search
+- **Darkfish** (deprecated) - The classic theme, will be removed in v8.0
+
+To use the Darkfish theme instead of the default Aliki theme:
+
+```shell
+rdoc --format darkfish
+```
+
+Or in your `.rdoc_options` file:
+
+```yaml
+generator_name: darkfish
+```
+
+There are also a few community-maintained themes for RDoc:
 
 - [rorvswild-theme-rdoc](https://github.com/BaseSecrete/rorvswild-theme-rdoc)
 - [hanna](https://github.com/jeremyevans/hanna) (a fork maintained by [Jeremy Evans](https://github.com/jeremyevans))
@@ -99,7 +116,7 @@ Please follow the theme's README for usage instructions.
 
 ## Bugs
 
-See CONTRIBUTING.rdoc for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.
 
 ## License
 

data/lib/rdoc/code_object/any_method.rb

@@ -351,7 +351,6 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     return call_seq unless is_alias_for || !aliases.empty?
 
     method_name = self.name
-    method_name = method_name[0, 1] if method_name =~ /\A\[/
 
     entries = call_seq.split "\n"
 
@@ -360,15 +359,24 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       ignore << is_alias_for.name
       ignore.concat is_alias_for.aliases.map(&:name)
     end
-    ignore.map! { |n| n =~ /\A\[/ ? /\[.*\]/ : n}
+
     ignore.delete(method_name)
-    ignore = Regexp.union(ignore)
+    ignore_bracket_methods, ignore_other_methods = ignore.partition {|i| i.start_with?('[') }
 
-    matching = entries.reject do |entry|
-      entry =~ /^\w*\.?#{ignore}[$\(\s]/ or
-        entry =~ /\s#{ignore}\s/
+    if ignore_other_methods.any?
+      ignore_union = Regexp.union(ignore_other_methods)
+      entries.reject! do |entry|
+        /\A(?:\w*\.)?#{ignore_union}(?:[(\s]|\z)/.match?(entry) ||
+          /\s#{ignore_union}\s/.match?(entry)
+      end
+    end
+    if ignore_bracket_methods.any?
+      entries.reject! do |entry|
+        # Ignore `receiver[arg] -> return_type` `[](arg)` `[]`
+        /\A\w*\[.*?\](?:[(\s]|\z)/.match?(entry)
+      end
     end
 
-    matching.empty? ? nil : matching.join("\n")
+    entries.empty? ? nil : entries.join("\n")
   end
 end

data/lib/rdoc/code_object/class_module.rb

@@ -689,6 +689,9 @@ class RDoc::ClassModule < RDoc::Context
 
   ##
   # Search record used by RDoc::Generator::JsonIndex
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -702,6 +705,16 @@ class RDoc::ClassModule < RDoc::Context
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the first comment for search results.
+
+  def search_snippet
+    first_comment = @comment_location.first&.first
+    return '' unless first_comment && !first_comment.empty?
+
+    snippet(first_comment)
+  end
+
   ##
   # Sets the store for this class or module and its contained code objects.
 

data/lib/rdoc/code_object/constant.rb

@@ -154,6 +154,15 @@ class RDoc::Constant < RDoc::CodeObject
     "#{@parent.path}##{@name}"
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if comment.empty?
+
+    snippet(comment)
+  end
+
   def pretty_print(q) # :nodoc:
     q.group 2, "[#{self.class.name} #{full_name}", "]" do
       unless comment.empty? then

data/lib/rdoc/code_object/method_attr.rb

@@ -375,6 +375,9 @@ class RDoc::MethodAttr < RDoc::CodeObject
   ##
   # Used by RDoc::Generator::JsonIndex to create a record for the search
   # engine.
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -384,10 +387,19 @@ class RDoc::MethodAttr < RDoc::CodeObject
       @parent.full_name,
       path,
       params,
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   def to_s # :nodoc:
     if @is_alias_for
       "#{self.class.name}: #{full_name} -> #{is_alias_for}"

data/lib/rdoc/code_object/top_level.rb

@@ -237,6 +237,9 @@ class RDoc::TopLevel < RDoc::Context
 
   ##
   # Search record used by RDoc::Generator::JsonIndex
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     return unless @parser < RDoc::Parser::Text
@@ -248,10 +251,19 @@ class RDoc::TopLevel < RDoc::Context
       '',
       path,
       '',
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   ##
   # Is this TopLevel from a text file instead of a source code file?
 

data/lib/rdoc/generator/aliki.rb

@@ -15,6 +15,30 @@ class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
     @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
@@ -39,4 +63,104 @@ class RDoc::Generator::Aliki < RDoc::Generator::Darkfish
       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
+
+  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/template/aliki/_head.rhtml

@@ -116,22 +116,22 @@
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/navigation.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_navigation.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/search.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_data.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/search_index.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_ranker.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 
 <script
-  src="<%= h asset_rel_prefix %>/js/searcher.js?v=<%= h RDoc::VERSION %>"
+  src="<%= h asset_rel_prefix %>/js/search_controller.js?v=<%= h RDoc::VERSION %>"
   defer
 ></script>
 

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

@@ -156,15 +156,13 @@
               <summary>Source</summary>
             </details>
           </div>
+          <div class="method-source-code" id="<%= method.html_name %>-source">
+            <pre class="<%= method.source_language %>" data-language="<%= method.source_language %>"><%= method.markup_code %></pre>
+          </div>
         <%- end %>
 
         <%- unless method.skip_description? then %>
         <div class="method-description">
-          <%- if method.token_stream then %>
-          <div class="method-source-code" id="<%= method.html_name %>-source">
-            <pre class="<%= method.source_language %>" data-language="<%= method.source_language %>"><%= method.markup_code %></pre>
-          </div>
-          <%- end %>
           <%- if method.mixin_from then %>
             <div class="mixin-from">
               <%= method.singleton ? "Extended" : "Included" %> from <a href="<%= klass.aref_to(method.mixin_from.path) %>"><%= method.mixin_from.full_name %></a>