Is it normal that YARD doesn't replace `code` with <code>code</code>?

Question

I'm just starting to use YARD for documenting my Rails app. I didn't specify any specific Markup handler, but I would have expected that `code` would be converted to code, which doesn't seem to happen. Is this normal behavior? Do I have to add some additional option to make this work? Thank you.

Pilothouse

Answer 1

The syntax is a little different from markdown (markdown vs rdoc) I suppose. Using '+' works. +code+ gets rendered in a <code> block.

Doyon

Answer 2

From GitHub, I was used to use backticks for inline code comments. So after some research I found the following, very nice solution.

• Add the redcarpet gem to your Gemfile
• Run bundle command
• Add --markup=markdown to your .yardopts file
• Start YARD server using yard server --reload
• Open localhost:8808 in your browser

Now you can use Syntax like on GitHub, e.g.

```ruby
def bla; puts 'bla'; end
```

Or

`this is inline code`

Nice! :)

Pilothouse

You can do the same while creating the docs itself: yardoc --markup=markdown|textile|rdoc(default) /path/to/sourcefile Works both ways – Doyon

Note that rubydoc.info uses .yardopts for configuration too, if your project contains it and you need custom options for your project. – Spoils

You can also leave the default markup (rdoc) for all source files and then override it on a per-file basis. So you can add the markdown markup to the README.md file, as described at the end of this section in official docs – Pia

Answer 3

Without markdown, YARD will display a code block for an indented line, e.g.

  # This is a useful POSIX regex:
  #   [[:lower:]]{2}[[:digit:]]{3}[[:lower:]]{2}[[:digit:]]{4}

Two spaces of indent seem to be sufficient.

Macario