ruby / ruby/rdoc

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

Open Beginner friendly
#1,761 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.