From 8993ab1d2099b7f2177abcc703f0f18966e81a92 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sat, 29 Jul 2023 17:39:04 -0500 Subject: [PATCH] Include project name and version in og:title This adds `ENV["HORO_PROJECT_NAME"]` and `ENV["HORO_BADGE_VERSION"]` to the `og:title` meta tag. The intent is to differentiate titles between different versions of the documentation. Note that `og:title` is typically an abridged form of the page title. `og:title` values longer than ~60 characters may be truncated. The string " (Ruby on Rails v7.0.0)" is 23 characters, leaving ~40 characters for the full module name. Most public modules in the Rails API appear to fall within that limit. But even for those that don't, the project version and name will be truncated first, leaving `og:title` no worse than before. --- lib/rdoc/generator/template/rails/class.rhtml | 2 +- lib/rdoc/generator/template/rails/file.rhtml | 2 ++ lib/sdoc/helpers.rb | 11 +++++--- spec/helpers_spec.rb | 26 +++++++++++++++++++ 4 files changed, 37 insertions(+), 4 deletions(-) diff --git a/lib/rdoc/generator/template/rails/class.rhtml b/lib/rdoc/generator/template/rails/class.rhtml index 5dc17803..33b3d65e 100644 --- a/lib/rdoc/generator/template/rails/class.rhtml +++ b/lib/rdoc/generator/template/rails/class.rhtml @@ -6,7 +6,7 @@ <%= include_template '_head.rhtml', {:context => klass, :tree_keys => klass.full_name.split('::') } %> - + <% unless (description = klass.description).empty? %> <% human_desc = truncate(strip_tags(description.gsub("\n", " ").strip)) %> diff --git a/lib/rdoc/generator/template/rails/file.rhtml b/lib/rdoc/generator/template/rails/file.rhtml index 41d2f710..4d6d4b62 100644 --- a/lib/rdoc/generator/template/rails/file.rhtml +++ b/lib/rdoc/generator/template/rails/file.rhtml @@ -5,6 +5,8 @@ <%= page_title file.name %> <%= include_template '_head.rhtml', {:context => file, :tree_keys => [] } %> + + diff --git a/lib/sdoc/helpers.rb b/lib/sdoc/helpers.rb index 301914e4..cda64a53 100644 --- a/lib/sdoc/helpers.rb +++ b/lib/sdoc/helpers.rb @@ -61,21 +61,26 @@ def canonical_url(context) end def project_name - @html_safe_project_name ||= h(ENV["HORO_PROJECT_NAME"]) if ENV["HORO_PROJECT_NAME"] + h(ENV["HORO_PROJECT_NAME"]) if ENV["HORO_PROJECT_NAME"] end def project_version - @html_safe_project_version ||= h(ENV["HORO_PROJECT_VERSION"]) if ENV["HORO_PROJECT_VERSION"] + h(ENV["HORO_PROJECT_VERSION"]) if ENV["HORO_PROJECT_VERSION"] end def badge_version - @html_safe_badge_version ||= h(ENV["HORO_BADGE_VERSION"]) if ENV["HORO_BADGE_VERSION"] + h(ENV["HORO_BADGE_VERSION"]) if ENV["HORO_BADGE_VERSION"] end def page_title(title = nil) h [title, @options.title].compact.join(" - ") end + def og_title(title) + project = [project_name, badge_version].join(" ").strip + "#{h title}#{" (#{project})" unless project.empty?}" + end + def group_by_first_letter(rdoc_objects) rdoc_objects.sort_by(&:name).group_by do |object| object.name[/^[a-z]/i]&.upcase || "#" diff --git a/spec/helpers_spec.rb b/spec/helpers_spec.rb index 1eb0bfe4..27b5bdcc 100644 --- a/spec/helpers_spec.rb +++ b/spec/helpers_spec.rb @@ -260,6 +260,32 @@ module Foo; module Bar; module Qux; end; end; end end end + describe "#og_title" do + it "includes ENV['HORO_PROJECT_NAME'] and ENV['HORO_BADGE_VERSION']" do + with_env("HORO_PROJECT_NAME" => "My Gem", "HORO_BADGE_VERSION" => "v2.0") do + _(@helpers.og_title("Foo")).must_equal "Foo (My Gem v2.0)" + end + + with_env("HORO_PROJECT_NAME" => "My Gem", "HORO_BADGE_VERSION" => nil) do + _(@helpers.og_title("Foo")).must_equal "Foo (My Gem)" + end + + with_env("HORO_PROJECT_NAME" => nil, "HORO_BADGE_VERSION" => "v2.0") do + _(@helpers.og_title("Foo")).must_equal "Foo (v2.0)" + end + + with_env("HORO_PROJECT_NAME" => nil, "HORO_BADGE_VERSION" => nil) do + _(@helpers.og_title("Foo")).must_equal "Foo" + end + end + + it "escapes the title" do + with_env("HORO_PROJECT_NAME" => "Ruby & Rails", "HORO_BADGE_VERSION" => "~> 1.0.0") do + _(@helpers.og_title("Foo")).must_equal "Foo<Bar> (Ruby & Rails ~> 1.0.0)" + end + end + end + describe "#group_by_first_letter" do it "groups RDoc objects by the first letter of their #name" do context = rdoc_top_level_for(<<~RUBY).find_module_named("Foo")