RDoc 8.0.0 gem omits doc/rdoc/example.rb, which is referenced by the packaged markup documentation #1761

Description

The RDoc repository contains doc/rdoc/example.rb, and the markup reference
relies on the code objects defined by that file.

However, doc/rdoc/example.rb is absent from the released RDoc 8.0.0 gem.

The gem does contain:

doc/markup_reference/rdoc.rdoc

That document contains references including:

rdoc-ref:RDoc::Example#instance_method_example
rdoc-ref:RDoc::Example::EXAMPLE_CONSTANT

When documentation is generated from the installed gem and the markup
reference is included, these links cannot be resolved.

The upstream source file is:

https://github.com/ruby/rdoc/blob/v8.0.0/doc/rdoc/example.rb

The references are in:

https://github.com/ruby/rdoc/blob/v8.0.0/doc/markup_reference/rdoc.rdoc

Reproduction

require "rubygems"

spec = Gem::Specification.find_by_name("rdoc", "8.0.0")

example = File.join(spec.full_gem_path, "doc/rdoc/example.rb")
reference = File.join(
  spec.full_gem_path,
  "doc/markup_reference/rdoc.rdoc"
)

p File.file?(example)   # => false
p File.file?(reference) # => true

Generate documentation from the installed gem while including
doc/markup_reference/rdoc.rdoc.

The resulting warnings include:

`rdoc-ref:RDoc::Example#instance_method_example` can't be resolved
`rdoc-ref:RDoc::Example::EXAMPLE_CONSTANT` can't be resolved

Expected behavior

All source files required by the packaged documentation should also be
included in the gem.

Suggested fix

Add doc/rdoc/example.rb to the gem package manifest:

non_lib_files = [
  # ...
  "doc/rdoc/example.rb",
]

It should probably also be included explicitly in extra_rdoc_files so
RubyGems documentation generation parses it:

s.extra_rdoc_files << "doc/rdoc/example.rb"

A packaging test could assert that every source file required by the markup
reference is present in the built gem.