Skip to content
This repository

Recognize Github Flavored Markdown #404

Closed
bytesource opened this Issue October 29, 2011 · 19 comments

9 participants

Stefan Rohlfing Loren Segal Timo Rößner Nikos Dimitrakopoulos Andy Lindeman Myron Marston Aaron Pfeifer Mark Evans
Stefan Rohlfing

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

Loren Segal
Owner

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

Loren Segal lsegal closed this October 29, 2011
Stefan Rohlfing

GFM is working now, thank you very much!

Loren Segal
Owner

No problem :)

Stefan Rohlfing

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?

Timo Rößner

Same issue here, identical yarddoc as @bytesource.

Loren Segal
Owner

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

Timo Rößner

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

Nikos Dimitrakopoulos

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!

Andy Lindeman

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

@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.

Loren Segal
Owner

@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.

Andy Lindeman

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!

Myron Marston

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.

Loren Segal
Owner

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?

Myron Marston

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

Localhost

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
Aaron Pfeifer

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

Loren Segal
Owner

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

Aaron Pfeifer

Bingo -- that was it. Thanks!

Mark Evans

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)

Mike Piccolo mfpiccolo referenced this issue from a commit January 11, 2014
Commit has since been removed from the repository and is no longer available.
Mike Piccolo mfpiccolo referenced this issue from a commit January 11, 2014
Commit has since been removed from the repository and is no longer available.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.