Recognize Github Flavored Markdown

[bytesource]

In my README files I use features from Github Flavored Markdown, such as code highlighting and awareness for underscores inside a word, but YARD does not recognize them.

Adding github-markup as a markup provider to .yardopts

-M github-markup

resulted in an error:

[error]: Invalid markup type 'markdown' or markup provider (github-markup) is not registered.

yard-0.7.3/lib/yard/templates/helpers/html_helper.rb:70:in `html_markup_markdown': undefined method `new' for nil:NilClass (NoMethodError)
[...]

Is there a way to make YARD parse Github Flavored Markdown? If not, I would suggest this as a new feature, especially because services like RubyDoc.info fetch their data from Github repos.

Stefan

[lsegal]

It works, but it relies on the redcarpet lib, use -M redcarpet.

[bytesource]

GFM is working now, thank you very much!

[lsegal]

No problem :)

[bytesource]

While YARD worked well with GitHub Flavored Markup locally after adding -M redcarpet to .yardopts, I realized that GFM still is not displayed correctly on rubydoc.info.

This is the content of my .yardopts file:

--no-private
--hide-void-return

--markup-provider=redcarpet
--markup=markdown

This is how the README should look like: https://github.com/bytesource/rstore/blob/master/README.md
This is how it is displayed on rubydocs.info: http://rubydoc.info/github/bytesource/rstore/master/file/README.md

Did I miss something or is the option -M redcarpet not recognized on rubydoc.info?

[troessner]

Same issue here, identical yarddoc as @bytesource.

[lsegal]

This is probably a rubydoc.info issue, we should open one on http://github.com/lsegal/rubydoc.info

[troessner]

@lsegal I just did....:-)

[nikosd]

just for the record (in case someone in the future reads this like me) here's what it takes to make this work :

In your Gemfile:

  gem 'yard'
  gem 'redcarpet'
  gem 'github-markup'

In your .yardopts

--markup-provider=redcarpet
--markup=markdown

Thanks!

[alindeman]

Is there a way to use redcarpet/markdown for the README but rdoc for the source files?

[ghost]

@alindeman
Append .md to your README, and use -m rdoc in .yardopts.

EDIT:
And nope, I don't think it is possible to specify the provider for markdown if your source markup language is rdoc, but you could try with -M redcarpet.

[lsegal]

@robgleeson @alindeman Note that this would require you to not have redcloth, kramdown, or bluecloth installed as a gem, or, if you are loading yard from bundler (bundle exec yard), only list the above gems in your gemfile. Unfortunately we don't currently bundle exec from rubydoc.info, and already have rdiscount installed, so this wouldn't work there. It's possible we might change the priority order for gems given the rising popularity for GFM.

[alindeman]

Nice, this works as long as rdiscount is not installed. Thanks for the tip.

$ yardoc */lib/**/*.rb - README.md

Definitely +1 for Github Flavored Markup in rdoc.info. Thanks again all!

[myronmarston]

Hmm...I can't get this to work at all :(.

I followed the instructions that @nikosd gave above. Can someone tell me what I'm doing wrong? My attempt to use GFM is here.

[lsegal]

Hmm...I can't get this to work at all :(.

I can't reproduce it not working. Note that the --markup-provider is no longer necessary as redcarpet is the default markdown provider now. Are you just looking to highlight a readme? Can you point to the specific parts that aren't working?

[myronmarston]

Here's what I'm seeing in my local browser:

It looks like it's working on rubydoc.info so I'm not sure what I'm doing wrong :(.

Here's my shell output from what I'm doing. Note that I'm deleting doc and .yardoc just in case I have some old artifacts that are preventing this form working (but it doesn't seem to make a difference either way).

➜  vcr git:(master) rm -rf doc
➜  vcr git:(master) rm -rf .yardoc
➜  vcr git:(master) yard doc
[warn]: Syntax error in `license`:(1,18): syntax error, unexpected tinteger, expecting $end
[warn]: in YARD::Handlers::Ruby::MethodHandler: Undocumentable method defined on object instance
[warn]:     in file 'lib/vcr/cassette/migrator.rb':49:

    49: def hash.each

yardFiles:          25
Modules:        10 (    0 undocumented)
Classes:        22 (    0 undocumented)
Constants:       3 (    0 undocumented)
Methods:        93 (   14 undocumented)
 89.06% documented
➜  vcr git:(master) yard server
>> YARD 0.7.4 documentation server at http://0.0.0.0:8808
[2011-12-22 12:14:52] INFO  WEBrick 1.3.1
[2011-12-22 12:14:52] INFO  ruby 1.9.2 (2011-07-09) [x86_64-darwin10.8.0]
[2011-12-22 12:14:52] INFO  WEBrick::HTTPServer#start: pid=7477 port=8808
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /docs/file/README.md HTTP/1.1" 200 11733
http://localhost:8808/ -> /docs/file/README.md
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /css/custom.css HTTP/1.1" 200 2209
http://localhost:8808/docs/file/README.md -> /css/custom.css
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /css/common.css HTTP/1.1" 200 42
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /js/jquery.js HTTP/1.1" 200 85925
http://localhost:8808/docs/file/README.md -> /css/common.css
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /js/app.js HTTP/1.1" 200 6492
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /css/style.css HTTP/1.1" 200 17034
http://localhost:8808/docs/file/README.md -> /js/jquery.js
http://localhost:8808/docs/file/README.md -> /js/app.js
http://localhost:8808/docs/file/README.md -> /css/style.css
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /js/autocomplete.js HTTP/1.1" 200 8003
http://localhost:8808/docs/file/README.md -> /js/autocomplete.js
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /js/live.js HTTP/1.1" 200 1031
http://localhost:8808/docs/file/README.md -> /js/live.js
local.seomoz.org - - [22/Dec/2011:12:15:01 PST] "GET /favicon.ico HTTP/1.1" 200 0
- -> /favicon.ico

[obrie]

I'm also having no luck with this. I've created the following project: https://github.com/obrie/gfm_doc_test

In that project, I've listed the gems installed (via gem list), the command used (bundle exec yard), and the generated output (in the output folder).

Any thoughts?

edit: May also be worth noting that this was generated using Ruby 1.8.7

[lsegal]

You should be using redcarpet 1.x, 2.x is not yet compatible with YARD. (2.x was released after 0.7.4 was)

[obrie]

Bingo -- that was it. Thanks!

[markevans]

Further to this (in case it helps anyone) - I was having problems using "bundle exec yardoc" because although I had changed my Gemfile to use redcarpet 1.x, redcarpet 2.x was still on my system.

I believe you need to gem uninstall redcarpet 2.x for it to work (I guess it's simply shelling out to the redcarpet command)

[weakish]

I was having problems using "bundle exec yardoc" because although I had changed my Gemfile to use redcarpet 1.x, redcarpet 2.x was still on my system.

I encountered a similar problem.

After uninstalling redcarpet 3.x and install 2.3.0, GFM works.

[burningTyger]

Yikes, this is not up to date, is it?