25

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.

Joshua Muheim
  • 12,617
  • 9
  • 76
  • 152

3 Answers3

21

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

Kashyap
  • 4,696
  • 24
  • 26
21

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! :)

Joshua Muheim
  • 12,617
  • 9
  • 76
  • 152
  • 3
    You can do the same while creating the docs itself: `yardoc --markup=markdown|textile|rdoc(default) /path/to/sourcefile` Works both ways – Kashyap Jul 27 '12 at 09:47
  • Note that http://rubydoc.info/ uses .yardopts for configuration too, if your project contains it and you need custom options for your project. – Smar Nov 06 '15 at 12:57
  • 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](https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#adding-meta-data-to-extra-files) – mucaho Sep 04 '22 at 13:20
9

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.

Darren Weber
  • 1,537
  • 19
  • 20