Ruby Yard documentation: how to add a "verbatim" (to generate something like a
tag)

Question

I want a piece of code, like a hash, to display with fixed typeface on the resulting html. Suppose this is the contents of my file:

=begin

One example of valid hash to this function is:
{
    :name => "Engelbert",
    :id  => 1345
}
=end
def f hash_param
  # ...
end

How to instruct yard (using the default of the version 0.9.15) so a yard doc file.rb will generate, for the hash example, the equivalent of adding 4 backslashes to the markdown format, or 4 starting empty spaces to stackoverflow, or the <pre> tag in html, resulting in a verbatim/fixed typeface format in the resulting html?

Expected output:

One example of valid hash to this function is:
{
    :name => "Engelbert",
    :id  => 1345
}

Daniel · Answer 1 · 2018-07-27T00:38:46.617

0

EDIT

> gem install redcarpet
> yard doc --markup-provider redcarpet --markup markdown - file.rb

Should wrap the contents of file.rb within a <pre> tag, producing this page.

Use @example

Show an example snippet of code for an object. The first line is an optional title.

# @example One example of valid hash to this function is:
#   {
#       :name => "Engelbert",
#       :id  => 1345
#   }
def f hash_param
  # ...
end

edited Jul 27 '18 at 00:38

answered Jul 26 '18 at 04:07

Daniel

11
3

ok, maybe the question was confusing, but, although what I what to display in the case above is an example, but I would like the solution to work for other cases too. Example of other cases: an ASCII art image displaying a super cow. – ribamar Jul 26 '18 at 15:07
I really appreciate your efforts and I really like the supercow there... but that's definitively not the answer -- the source code isn't to be output. I think that's better to admit that it's probably not possible to do it. – ribamar Aug 09 '18 at 14:45

score 0 · Answer 2 · answered Jun 01 '21 at 10:36

Maybe I don't get your question:

the equivalent of adding 4 backslashes to the markdown format, or 4 starting empty spaces to stackoverflow

If I use the 4 starting empty spaces in my code like this:

=begin

One example of valid hash to this function is:
    {
        :name => "Engelbert",
        :id  => 1345
    }
=end
def f hash_param
  # ...
end

then I get

But maybe you can also use @option:

@param hash_param
@option hash_param [String] :name The name of...
@option hash_param [Integer] :id The id of...

and you get:

Disclaimer: I used yard 0.9.26 for my examples.

Ruby Yard documentation: how to add a "verbatim" (to generate something like a tag)

2 Answers2

EDIT

Ruby Yard documentation: how to add a "verbatim" (to generate something like a
tag)