From 31b27b37129d6b764f5941ec996a643e6c4c48ed Mon Sep 17 00:00:00 2001 From: Jarek Radosz Date: Mon, 17 Jan 2022 18:32:07 +0100 Subject: [PATCH] FIX: Broken GitHub folder onebox logic (#15612) 1. `html_doc.css('.Box.md')` always returns a truthy value (e.g. `[]`) so the second branch of the if-elsif never ran 2. `node&.css('text()')` was invalid code that would raise an error 3. Matching on h3 elements is no longer correct with the current html structure returned by GitHub --- lib/onebox/engine/github_folder_onebox.rb | 8 +- .../onebox/githubfolder-rdoc-root.response | 2391 +++++++++++++++++ .../engine/github_folder_onebox_spec.rb | 13 + 3 files changed, 2406 insertions(+), 6 deletions(-) create mode 100644 spec/fixtures/onebox/githubfolder-rdoc-root.response diff --git a/lib/onebox/engine/github_folder_onebox.rb b/lib/onebox/engine/github_folder_onebox.rb index fb8bbe1e204..aae75888be0 100644 --- a/lib/onebox/engine/github_folder_onebox.rb +++ b/lib/onebox/engine/github_folder_onebox.rb @@ -26,14 +26,10 @@ module Onebox if fragment fragment = Addressable::URI.unencode(fragment) - if html_doc.css('.Box.md') - # For links to markdown docs + # For links to markdown and rdoc + if html_doc.css(".Box.md, .Box.rdoc").present? node = html_doc.css('a.anchor').find { |n| n['href'] == "##{fragment}" } subtitle = node&.parent&.text - elsif html_doc.css('.Box.rdoc') - # For links to rdoc docs - node = html_doc.css('h3').find { |n| n['id'] == "user-content-#{fragment.downcase}" } - subtitle = node&.css('text()')&.first&.text end title = "#{title} - #{subtitle}" if subtitle diff --git a/spec/fixtures/onebox/githubfolder-rdoc-root.response b/spec/fixtures/onebox/githubfolder-rdoc-root.response new file mode 100644 index 00000000000..ffbe26ca1ad --- /dev/null +++ b/spec/fixtures/onebox/githubfolder-rdoc-root.response @@ -0,0 +1,2391 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GitHub - ruby/rdoc: RDoc produces HTML and online documentation for Ruby projects. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Skip to content + + + + + + + + + + +
+ +
+ + + + + + + +
+ + + +
+ + + + + + + + + + +
+
+
+ + + + + + + + + + + + + + + +
+ +
+ +
+

+ + + / + + rdoc + + + Public +

+ +
+ + + +
+ +
+
+

+ RDoc produces HTML and online documentation for Ruby projects. +

+
+ + + ruby.github.io/rdoc/ + +
+
+ + + View license + +
+
+ + + 694 + stars + + + 403 + forks +
+
+
+
+ + Star + +
+
+
+ Notifications + +
+
+
+ +
+ + + + +
+ + + +
+
+ + + + + + + + +
+
+ +
+ +
+
+ +
+ +
+
+ + + master + + + + +
+
+
+ Switch branches/tags + +
+ + + +
+ +
+ +
+ + +
+ +
+ + + + + + + + + + + + + + + + +
+ + + + +
+
+ +
+ +
+ + +
+ + + 7 + branches + + + + 82 + tags + +
+ +
+ + + + + + + + +
+ Code +
+
+ + + + + + +
+
+
+ + + + + +
+ + + + +
+
+

Latest commit

+
+ +
+
 
+
+

Git stats

+ +
+
+
+

Files

+ + + + Permalink + +
+ + + Failed to load latest commit information. + + + +
+
+
+
Type
+
Name
+
Latest commit message
+
Commit time
+
+ +
+
+ +
+ +
+ .github/workflows +
+ +
+ + Skip Ruby 2.5 + +
+ +
+ Dec 28, 2021 +
+ +
+
+
+ +
+ +
+ bin +
+ +
+ + migrated bundle gem styles + +
+ +
+ Sep 6, 2016 +
+ +
+
+
+ +
+ +
+ exe +
+ +
+ + migrated bundle gem styles + +
+ +
+ Sep 6, 2016 +
+ +
+
+
+ +
+ +
+ lib +
+ +
+ + Optimize RawLine by using a regexp instead of negative look-ahead rule + +
+ +
+ Dec 28, 2021 +
+ +
+
+
+ +
+ +
+ man +
+ +
+ + ri.1: rewrite ri man page + +
+ +
+ Aug 2, 2020 +
+ +
+
+
+ +
+ +
+ test/rdoc +
+ +
+ + Removed redundant tests + +
+ +
+ Dec 24, 2021 +
+ +
+
+
+ +
+ +
+ .document +
+ +
+ + Import various improvements from Thierry Lambert. See History.txt. + +
+ +
+ Sep 10, 2010 +
+ +
+
+
+ +
+ +
+ .gitignore +
+ +
+ + Gitignore coverage folder + +
+ +
+ Feb 16, 2019 +
+ +
+
+
+ +
+ +
+ .rubocop.yml +
+ +
+ + Added initial rubocop rule + +
+ +
+ Sep 7, 2018 +
+ +
+
+
+ +
+ +
+ CONTRIBUTING.rdoc +
+ +
+ + Fix broken links + +
+ +
+ Sep 29, 2017 +
+ +
+
+
+ +
+ +
+ CVE-2013-0256.rdoc +
+ +
+ + Fix CVE-2013-0256, an XSS exploit in RDoc + +
+ +
+ Feb 6, 2013 +
+ +
+
+
+ +
+ +
+ ExampleMarkdown.md +
+ +
+ + Improve wording in markup output examples + +
+ +
+ Jul 9, 2013 +
+ +
+
+
+ +
+ +
+ ExampleRDoc.rdoc +
+ +
+ + Improve wording in markup output examples + +
+ +
+ Jul 9, 2013 +
+ +
+
+
+ +
+ +
+ Gemfile +
+ +
+ + minitest is not need to run rubygems test now + +
+ +
+ Sep 3, 2021 +
+ +
+
+
+ +
+ +
+ History.rdoc +
+ +
+ + format + +
+ +
+ Feb 24, 2017 +
+ +
+
+
+ +
+ +
+ LEGAL.rdoc +
+ +
+ + s/Sdoc/SDoc [ci skip] + +
+ +
+ Mar 25, 2016 +
+ +
+
+
+ +
+ +
+ LICENSE.rdoc +
+ +
+ + Convert LICENSE to rdoc + +
+ +
+ Sep 23, 2011 +
+ +
+
+
+ +
+ +
+ README.rdoc +
+ +
+ + Removed CI status badge for Travis. + +
+ +
+ Aug 11, 2019 +
+ +
+
+
+ +
+ +
+ RI.rdoc +
+ +
+ + Rename txt documentation files to "rdoc" + +
+ +
+ Sep 29, 2011 +
+ +
+
+
+ +
+ +
+ Rakefile +
+ +
+ + Add "rake clean" task to erase generated parser files + +
+ +
+ Aug 9, 2021 +
+ +
+
+
+ +
+ +
+ TODO.rdoc +
+ +
+ + Update TODO from accessibility call + +
+ +
+ Dec 26, 2013 +
+ +
+
+
+ +
+ +
+ rdoc.gemspec +
+ +
+ + Move dev dependency of gettext to Gemfile + +
+ +
+ Aug 9, 2021 +
+ +
+
+
+
+
+ + + + +
+ + + +
+ +
+
+
+ + + + + + +
+ + +
+ RDoc - Ruby Documentation System¶ ↑ + Description¶ ↑ + Generating Documentation¶ ↑ + Writing Documentation¶ ↑ + Bugs¶ ↑ + License¶ ↑ + Warranty¶ ↑ +
+
+ +
+ +

+ README.rdoc +

+
+
+ +
+
+

RDoc - Ruby Documentation System ↑

+
home +
+

github.com/ruby/rdoc

+
rdoc +
+

ruby.github.io/rdoc

+
bugs +
+

github.com/ruby/rdoc/issues

+
code quality +
+

Code Climate

+
+ +

Description ↑

+ +

RDoc produces HTML and command-line documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying documentation from the command-line.

+ +

Generating Documentation ↑

+ +

Once installed, you can create documentation using the rdoc command

+ +
$ rdoc [options] [names...]
+ +

For an up-to-date option summary, type

+ +
$ rdoc --help
+ +

A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).

+ +
$ rdoc
+ +

This command generates documentation for all the Ruby and C source files in and below the current directory. These will be stored in a documentation tree starting in the subdirectory doc.

+ +

You can make this slightly more useful for your readers by having the index page contain the documentation for the primary file. In our case, we could type

+ +
% rdoc --main README.rdoc
+ +

You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.

+ +

RDoc uses file extensions to determine how to process each file. File names ending .rb and .rbw are assumed to be Ruby source. Files ending .c are parsed as C files. All other files are assumed to contain just Markup-style markup (with or without leading '#' comment markers). If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.

+ +

To generate documentation using rake see RDoc::Task.

+ +

To generate documentation programmatically:

+ +
gem 'rdoc'
+require 'rdoc/rdoc'
+
+options = RDoc::Options.new
+# see RDoc::Options
+
+rdoc = RDoc::RDoc.new
+rdoc.document options
+# see RDoc::RDoc
+
+ +

Writing Documentation ↑

+ +

To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:

+ +
##
+# This class represents an arbitrary shape by a series of points.
+
+class Shape
+
+  ##
+  # Creates a new shape described by a +polyline+.
+  #
+  # If the +polyline+ does not end at the same point it started at the
+  # first pointed is copied and placed at the end of the line.
+  #
+  # An ArgumentError is raised if the line crosses itself, but shapes may
+  # be concave.
+
+  def initialize polyline
+    # ...
+  end
+
+end
+
+ +

The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported. You can set the default comment format for your entire project by creating a .rdoc_options file. See RDoc::Options@Saved+Options for instructions on creating one. You can also set the comment format for a single file through the :markup: directive, but this is only recommended if you wish to switch markup formats. See RDoc::Markup@Other+directives.

+ +

Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.

+ +

See RDoc::Parser::C for documenting C extensions with RDoc.

+ +

To determine how well your project is documented run rdoc -C lib to get a documentation coverage report. rdoc -C1 lib includes parameter names in the documentation coverage report.

+ +

Bugs ↑

+ +

See CONTRIBUTING@Bugs 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 ↑

+ +

RDoc is Copyright © 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions © 2007-2011 Eric Hodel. Portions copyright others, see individual files and LEGAL.rdoc for details.

+ +

RDoc is free software, and may be redistributed under the terms specified in LICENSE.rdoc.

+ +

Warranty ↑

+ +

This software is provided “as is” and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

+
+
+
+ + + + +
+
+ +
+
+
+

About

+ +

+ RDoc produces HTML and online documentation for Ruby projects. +

+
+ + + ruby.github.io/rdoc/ + +
+ +

Topics

+
+
+ + ruby + + + documentation-tool + +
+ +
+ +

Resources

+
+ + + Readme +
+ +

License

+
+ + + View license + +
+ + + + + +

Stars

+
+ + + 694 + stars +
+ +

Watchers

+
+ + + 53 + watching +
+ +

Forks

+
+ + + 403 + forks +
+ +
+
+
+
+

+ + Releases +

+ + + + 82 + tags + +
+
+
+
+

+ + Packages +

+ + +
+ No packages published
+
+ + + +
+
+
+
+ + +

+ + Used by 657k +

+ + +
    +
  • + @dveeden +
    • +
  • + @anilnabin25 +
    • +
  • + @anilnabin25 +
    • +
  • + @anilnabin25 +
    • +
  • + @anilnabin25 +
    • +
  • + @EttyDaniel +
    • +
  • + @rothfield +
    • +
  • + @vulsio +
    • +
+ + + 656,817 + + + +
+
+
+
+

+ + Contributors 92 +

+ + + + + + + + +
+ + + 81 contributors +
+
+
+
+
+

Languages

+
+ + + + + +
+ + +
+
+
+
+ +
+ + + +
+
+ +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + diff --git a/spec/lib/onebox/engine/github_folder_onebox_spec.rb b/spec/lib/onebox/engine/github_folder_onebox_spec.rb index 3212b0dfae4..3ea103792c5 100644 --- a/spec/lib/onebox/engine/github_folder_onebox_spec.rb +++ b/spec/lib/onebox/engine/github_folder_onebox_spec.rb @@ -41,4 +41,17 @@ describe Onebox::Engine::GithubFolderOnebox do expect(@onebox.to_html).to include("discourse/discourse - Setting up Discourse") end end + + context 'with rdoc fragments' do + before do + @link = "https://github.com/ruby/rdoc#description-" + @uri = "https://github.com/ruby/rdoc" + stub_request(:get, @uri).to_return(status: 200, body: onebox_response("githubfolder-rdoc-root")) + @onebox = described_class.new(@link) + end + + it "extracts subtitles when linking to docs" do + expect(@onebox.to_html).to include("GitHub - ruby/rdoc: RDoc produces HTML and online documentation for Ruby... - Description¶ ↑") + end + end end