RDoc 8.0.0 gem omits `doc/rdoc/example.rb`, which is referenced by the packaged markup documentation
Nobody has claimed this yet.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 465
- Avg merge
- 3d 10h
- Merged PRs (30d)
- 27
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the gem packaging configuration and compare it with doc/rdoc/example.rb and doc/markup_reference/rdoc.rdoc. Reproduce the missing-file check against the built RDoc 8.0.0 gem, then verify that the packaged file is available to documentation generation and the referenced RDoc links resolve without warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ruby
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100