Generate meta tags for each type of page based on content

Author: vinistock

Rakefile

@@ -25,10 +25,6 @@ RDoc::Task.new do |doc|
   doc.title = "rdoc #{RDoc::VERSION} Documentation"
   doc.rdoc_dir = '_site' # for github pages
   doc.rdoc_files = FileList.new %w[lib/**/*.rb *.rdoc doc/rdoc/markup_reference.rb] - PARSER_FILES
-  doc.meta_tags = {
-    "description" => "Documentation for RDoc, the Ruby documentation generator",
-    "keywords" => "rdoc,ruby,documentation,generator"
-  }
 end
 
 task "coverage" do

lib/rdoc/generator/darkfish.rb

@@ -783,4 +783,18 @@ def template_for file, page = true, klass = ERB
     template
   end
 
+  # Returns an excerpt of the content for usage in meta description tags
+  def excerpt(content)
+    text = content.is_a?(RDoc::Comment) ? content.text : content
+
+    # Try to select the text up to the second paragraph, the first paragraph or the first 150 characters
+    excerpt_end = text.index(".")
+    excerpt_end = if excerpt_end
+      text.index(".", excerpt_end + 1) || excerpt_end
+    else
+      150
+    end
+
+    text[0...excerpt_end].gsub(/\n/, ' ').squeeze(" ")
+  end
 end

lib/rdoc/generator/template/darkfish/_head.rhtml

@@ -2,8 +2,26 @@
 
 <title><%= h @title %></title>
 
-<%- @options.meta_tags.each do |name, content| -%>
-<meta name="<%= h name %>" content="<%= h content %>">
+<%- 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 -%>
 
 <script type="text/javascript">

lib/rdoc/options.rb

@@ -344,12 +344,6 @@ class RDoc::Options
   # Indicates if files of test suites should be skipped
   attr_accessor :skip_tests
 
-  ##
-  # Meta tags to be included in the HTML header, such as keywords, description,
-  # author and others. This option is a hash where the keys are the meta tag
-  # name and the values are the content of the meta tag.
-  attr_accessor :meta_tags
-
   def initialize loaded_options = nil # :nodoc:
     init_ivars
     override loaded_options if loaded_options
@@ -398,7 +392,6 @@ def init_ivars # :nodoc:
     @encoding = Encoding::UTF_8
     @charset = @encoding.name
     @skip_tests = true
-    @meta_tags = {}
   end
 
   def init_with map # :nodoc:
@@ -423,7 +416,6 @@ def init_with map # :nodoc:
     @title          = map['title']
     @visibility     = map['visibility']
     @webcvs         = map['webcvs']
-    @meta_tags      = map['meta_tags']
 
     @rdoc_include = sanitize_path map['rdoc_include']
     @static_path  = sanitize_path map['static_path']
@@ -456,7 +448,6 @@ def override map # :nodoc:
     @title          = map['title']          if map.has_key?('title')
     @visibility     = map['visibility']     if map.has_key?('visibility')
     @webcvs         = map['webcvs']         if map.has_key?('webcvs')
-    @meta_tags      = map['meta_tags']      if map.has_key?('meta_tags')
 
     if map.has_key?('rdoc_include')
       @rdoc_include = sanitize_path map['rdoc_include']
@@ -484,8 +475,7 @@ def == other # :nodoc:
       @template       == other.template       and
       @title          == other.title          and
       @visibility     == other.visibility     and
-      @webcvs         == other.webcvs         and
-      @meta_tags      == other.meta_tags
+      @webcvs         == other.webcvs
   end
 
   ##
@@ -802,15 +792,6 @@ def parse argv
 
       opt.separator nil
 
-      opt.on("-mTAGS", "--meta-tags=TAGS",
-             "Meta tags to be included in the HTML head") do |value|
-        @meta_tags = JSON.parse(value)
-      rescue  JSON::ParserError, TypeError
-        raise OptionParser::InvalidArgument, "Invalid value for --meta-tags. Should be a JSON string"
-      end
-
-      opt.separator nil
-
       opt.on("--extension=NEW=OLD", "-E",
              "Treat files ending with .new as if they",
              "ended with .old. Using '-E cgi=rb' will",

lib/rdoc/task.rb

@@ -35,7 +35,6 @@
 require_relative '../rdoc'
 require 'rake'
 require 'rake/tasklib'
-require "json"
 
 ##
 # RDoc::Task creates the following rake tasks to generate and clean up RDoc
@@ -152,12 +151,6 @@ class RDoc::Task < Rake::TaskLib
 
   attr_accessor :external
 
-  ##
-  # Meta tags to be included in the HTML header, such as keywords, description,
-  # author and others. This option is a hash where the keys are the meta tag
-  # name and the values are the content of the meta tag.
-  attr_accessor :meta_tags
-
   ##
   # Create an RDoc task with the given name. See the RDoc::Task class overview
   # for documentation.
@@ -208,7 +201,6 @@ def defaults
     @template = nil
     @generator = nil
     @options = []
-    @meta_tags = nil
   end
 
   ##
@@ -279,13 +271,12 @@ def define
 
   def option_list
     result = @options.dup
-    result << "-o"          << @rdoc_dir
-    result << "--main"      << main      if main
-    result << "--markup"    << markup    if markup
-    result << "--title"     << title     if title
-    result << "-T"          << template  if template
-    result << '-f'          << generator if generator
-    result << '--meta-tags' << meta_tags.to_json if meta_tags
+    result << "-o"       << @rdoc_dir
+    result << "--main"   << main      if main
+    result << "--markup" << markup    if markup
+    result << "--title"  << title     if title
+    result << "-T"       << template  if template
+    result << '-f'       << generator if generator
     result
   end
 

test/rdoc/test_rdoc_generator_darkfish.rb

@@ -322,19 +322,48 @@ def test_title_escape
     assert_main_title(File.binread('index.html'), title)
   end
 
-  def test_meta_tags
-    @options.meta_tags = {
-      "keywords" => "ruby,programming,software",
-      "description" => "RDoc is an awesome documentation generator for Ruby!"
-    }
+  def test_meta_tags_for_index
+    @options.title = "My awesome Ruby project"
     @g.generate
 
     content = File.binread("index.html")
 
-    assert_match("<meta name=\"keywords\" content=\"ruby,programming,software\">", content)
-    assert_match(
-      "<meta name=\"description\" content=\"RDoc is an awesome documentation generator for Ruby!\">",
-      content
+    assert_include(content, '<meta name="keywords" content="ruby,documentation,My awesome Ruby project">')
+    assert_include(content, '<meta name="description" content="Documentation for My awesome Ruby project">')
+  end
+
+  def test_meta_tags_for_classes
+    top_level = @store.add_file("file.rb")
+    top_level.add_class(@klass.class, @klass.name)
+    inner = @klass.add_class(RDoc::NormalClass, "Inner")
+    inner.add_comment("This is a normal class. It is fully documented.", top_level)
+
+    @g.generate
+
+    content = File.binread("Klass/Inner.html")
+    assert_include(content, '<meta name="keywords" content="ruby,class,Klass::Inner">')
+    assert_include(
+      content,
+      '<meta name="description" content="class Klass::Inner: This is a normal class. It is fully documented">',
+    )
+  end
+
+  def test_meta_tags_for_pages
+    top_level = @store.add_file("CONTRIBUTING.rdoc", parser: RDoc::Parser::Simple)
+    top_level.comment = <<~RDOC
+      = Contributing
+
+      Here are the instructions for contributing. Begin by installing Ruby.
+    RDOC
+
+    @g.generate
+
+    content = File.binread("CONTRIBUTING_rdoc.html")
+    assert_include(content, '<meta name="keywords" content="ruby,documentation,CONTRIBUTING">')
+    assert_include(
+      content,
+      "<meta name=\"description\" content=\"CONTRIBUTING: = Contributing Here are the instructions for contributing." \
+      " Begin by installing Ruby\">",
     )
   end
 

test/rdoc/test_rdoc_options.rb

@@ -83,7 +83,6 @@ def test_to_yaml
       'visibility'           => :protected,
       'webcvs'               => nil,
       'skip_tests'           => true,
-      'meta_tags'            => {},
     }
 
     assert_equal expected, coder