Skip to content

Commit

Permalink
Version explicit links to api.rubyonrails.org
Browse files Browse the repository at this point in the history
Similar to ffcaf81, this uses
postprocessing to version explicit links to api.rubyonrails.org.  For
example, if `ENV["HORO_PROJECT_VERSION"]` is "3.2.1" (and
`ENV["HORO_PROJECT_NAME"]` is "Ruby on Rails"), then

  ```html
  <a href="https://api.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>
  ```

will be changed to

  ```html
  <a href="https://api.rubyonrails.org/v3.2.1/classes/ActiveRecord/Base.html">Learn more</a>
  ```

This allows such URLs to be used in `README.rdoc` files instead of using
`link:classes/ActiveRecord/Base.html`, which is not properly resolved
when the link is rendered on e.g. GitHub.
  • Loading branch information
jonathanhefner committed Nov 14, 2023
1 parent aa00bf0 commit 87683a1
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 6 deletions.
9 changes: 6 additions & 3 deletions lib/sdoc/postprocessor.rb
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ def process(rendered)
document = Nokogiri::HTML5.parse(rendered)

rebase_urls!(document)
version_rails_guides_urls!(document)
version_rubyonrails_urls!(document)
add_ref_link_classes!(document)
unify_h1_headings!(document)
highlight_code_blocks!(document)
Expand Down Expand Up @@ -49,9 +49,12 @@ def rebase_url(url, current_path)
end
end

def version_rails_guides_urls!(document)
def version_rubyonrails_urls!(document)
if ENV["HORO_PROJECT_NAME"] == "Ruby on Rails" && version = ENV["HORO_PROJECT_VERSION"]
document.css("a[href^='https://guides.rubyonrails.org/']").each do |element|
document.css(
"a[href^='https://api.rubyonrails.org/']",
"a[href^='https://guides.rubyonrails.org/']"
).each do |element|
element["href"] = version_url(element["href"], version)
end
end
Expand Down
26 changes: 23 additions & 3 deletions spec/postprocessor_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,24 @@
_(postprocessed).must_include expected_body
end

it "versions Rails API Docs URLs based on ENV['HORO_PROJECT_VERSION']" do
rendered = <<~HTML
<a href="https://api.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>
HTML

{
"3.2.1" => %(<a href="https://api.rubyonrails.org/v3.2.1/classes/ActiveRecord/Base.html">Learn more</a>),
"v3.2.1" => %(<a href="https://api.rubyonrails.org/v3.2.1/classes/ActiveRecord/Base.html">Learn more</a>),
"main@1337c0d3" => %(<a href="https://edgeapi.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>),
"edge" => %(<a href="https://edgeapi.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>),
nil => %(<a href="https://api.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>),
}.each do |version, expected|
with_env("HORO_PROJECT_VERSION" => version, "HORO_PROJECT_NAME" => "Ruby on Rails") do
_(SDoc::Postprocessor.process(rendered)).must_include expected
end
end
end

it "versions Rails guides URLs based on ENV['HORO_PROJECT_VERSION']" do
rendered = <<~HTML
<a href="https://guides.rubyonrails.org/testing.html">Testing</a>
Expand All @@ -47,14 +65,16 @@
end
end

it "does not version Rails guides URLs when ENV['HORO_PROJECT_NAME'] is not Ruby on Rails" do
it "does not version rubyonrails.org URLs when ENV['HORO_PROJECT_NAME'] is not Ruby on Rails" do
rendered = <<~HTML
<a href="https://api.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>
<a href="https://guides.rubyonrails.org/testing.html">Testing</a>
HTML

with_env("HORO_PROJECT_VERSION" => "3.2.1", "HORO_PROJECT_NAME" => "My Rails Gem") do
_(SDoc::Postprocessor.process(rendered)).
must_include %(<a href="https://guides.rubyonrails.org/testing.html">Testing</a>)
postprocessed = _(SDoc::Postprocessor.process(rendered))
postprocessed.must_include %(<a href="https://api.rubyonrails.org/classes/ActiveRecord/Base.html">Learn more</a>)
postprocessed.must_include %(<a href="https://guides.rubyonrails.org/testing.html">Testing</a>)
end
end

Expand Down

0 comments on commit 87683a1

Please sign in to comment.