New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Recognize Github Flavored Markdown #404

Closed
bytesource opened this Issue Oct 30, 2011 · 21 comments

Comments

Projects
None yet
10 participants
@bytesource

bytesource commented Oct 30, 2011

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

This comment has been minimized.

Show comment
Hide comment
@lsegal

lsegal Oct 30, 2011

Owner

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

Owner

lsegal commented Oct 30, 2011

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

@lsegal lsegal closed this Oct 30, 2011

@bytesource

This comment has been minimized.

Show comment
Hide comment
@bytesource

bytesource Oct 30, 2011

GFM is working now, thank you very much!

bytesource commented Oct 30, 2011

GFM is working now, thank you very much!

@lsegal

This comment has been minimized.

Show comment
Hide comment
@lsegal

lsegal Oct 30, 2011

Owner

No problem :)

Owner

lsegal commented Oct 30, 2011

No problem :)

@bytesource

This comment has been minimized.

Show comment
Hide comment
@bytesource

bytesource Nov 4, 2011

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?

bytesource commented Nov 4, 2011

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

This comment has been minimized.

Show comment
Hide comment
@troessner

troessner Nov 10, 2011

Same issue here, identical yarddoc as @bytesource.

troessner commented Nov 10, 2011

Same issue here, identical yarddoc as @bytesource.

@lsegal

This comment has been minimized.

Show comment
Hide comment
@lsegal

lsegal Nov 10, 2011

Owner

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

Owner

lsegal commented Nov 10, 2011

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

@troessner

This comment has been minimized.

Show comment
Hide comment
@troessner

troessner Nov 11, 2011

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

troessner commented Nov 11, 2011

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

@nikosd

This comment has been minimized.

Show comment
Hide comment
@nikosd

nikosd Nov 22, 2011

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!

nikosd commented Nov 22, 2011

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

This comment has been minimized.

Show comment
Hide comment
@alindeman

alindeman Nov 26, 2011

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

alindeman commented Nov 26, 2011

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

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Nov 26, 2011

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

ghost commented Nov 26, 2011

@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

This comment has been minimized.

Show comment
Hide comment
@lsegal

lsegal Nov 26, 2011

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.

Owner

lsegal commented Nov 26, 2011

@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

This comment has been minimized.

Show comment
Hide comment
@alindeman

alindeman Nov 26, 2011

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!

alindeman commented Nov 26, 2011

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

This comment has been minimized.

Show comment
Hide comment
@myronmarston

myronmarston Dec 22, 2011

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.

myronmarston commented Dec 22, 2011

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

This comment has been minimized.

Show comment
Hide comment
@lsegal

lsegal Dec 22, 2011

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?

Owner

lsegal commented Dec 22, 2011

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

This comment has been minimized.

Show comment
Hide comment
@myronmarston

myronmarston Dec 22, 2011

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

myronmarston commented Dec 22, 2011

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

This comment has been minimized.

Show comment
Hide comment
@obrie

obrie Dec 31, 2011

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

obrie commented Dec 31, 2011

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

This comment has been minimized.

Show comment
Hide comment
@lsegal

lsegal Dec 31, 2011

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)

Owner

lsegal commented Dec 31, 2011

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

This comment has been minimized.

Show comment
Hide comment
@obrie

obrie Dec 31, 2011

Bingo -- that was it. Thanks!

obrie commented Dec 31, 2011

Bingo -- that was it. Thanks!

@markevans

This comment has been minimized.

Show comment
Hide comment
@markevans

markevans Feb 17, 2012

Contributor

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)

Contributor

markevans commented Feb 17, 2012

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

This comment has been minimized.

Show comment
Hide comment
@weakish

weakish Nov 24, 2014

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.

weakish commented Nov 24, 2014

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.

inz added a commit to sealuzh/cloud-stove that referenced this issue Jan 26, 2017

@burningTyger

This comment has been minimized.

Show comment
Hide comment
@burningTyger

burningTyger Mar 13, 2017

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

burningTyger commented Mar 13, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment