When the markdown provider is redcarpet PHP-markdown style tables should be rendered.

[ghost]

The documentation(http://rdoc.info/github/tanoku/redcarpet/master/file/README.markdown) seems to suggest you can add support for PHP-markdown style tables by passing an option to Markdown.new(…). It'd be cool if YARD could support this out of the box.

[lsegal]

Closing this because unfortunately I don't have enough time to take a stab at this feature-- I do think it would be a useful addition though. If you want to implement it and submit a pull request with proper tests I would likely merge it in.

[ghost]

@lsegal Okay, I'll do it.

[akzhan]

Has been reimplemented as yard-redcarpet-ext plugin (available as yard-redcarpet-ext gem). See https://github.com/regru/yard-redcarpet-ext-plugin for details

[ghost]

I dropped the ball on this one. thanks for this @akzhan.
do we need a separate file to define the options? my only concern. it feels a bit weird to
collect ".yardopts" and "yard_redcarpet_ext" ? I can see how namespace conflict might arise, but maybe a single key as a namespace to collect these options(in .yardopts) could work well too?

[akzhan]

You need separate .yard_redcarpet_ext file with tables in.

This is because YARD Configuration class is hard to extend.

[akzhan]

Looks like regru/reg_api2-ruby@75ae738

[ghost]

i wonder how we could make this better. is there an API you can think of?
--plugin-options=tables is all I can come up with(passing tables infers tables=true, not passing infers it is false or the default value).

[ghost]

maybe something generic like .yard_plugin_options that map to keys&values.
thanks again @akzhan I will start using this :)

[akzhan]

All of these ways need to change YARD itself. This way was revoked by @lsegal.

You have another option to use environment variable named YARD_REDCARPET_EXTS.

[ghost]

indeed, that's fine. i think this needs a solution from YARD, if I use X plugins I have X custom files?
seems like yard_plugins.yml could look like this:

redcarpet_ext: 
  tables: true

did you propose the same?

[akzhan]

Yes, we need any mechanism to provide plugin options with yard ones. But it must be resolved by @lsegal, I suppose.

[lsegal]

You don't need a separate file per plugin. You can always add options to the yard doc command the same way that @akzhan added it in #698. The only problem with adding args is if the args you add have to be processed before the options get registered (which is why I pointed out it can be an awkward story), but in the case of this plugin I think it would be fine to register switches.

Of course failing switches there is always the option to use environment variables, which also avoids separate files.

In other words, it's already possible to do this.

[akzhan]

@lsegal These options will be reported by YARD as unrecognnized I suppose. This is because plugin loads at same phase as parsing of config.

[akzhan]

Now yard-redcarpet-ext supports tables extension by default, as GitHub does.

[seanlinsley]

FWIW, I found this thread trying to move existing docs from rdoc to markdown, and your gem was just what I needed @akzhan. Thanks 🌵

[akzhan]

Tables now supported on http://rubydoc.info (docmeta/rubydoc.info#67). Thanks to @lsegal.

[ghost]

w00t!

[bclennox]

@lsegal Is there any reason not to include tables in the default set of Redcarpet options for YARD? It took me a while to figure out why they weren't rendering by default (since they were rendering correctly on GitHub), and it seems heavy-handed to depend on another gem for that one configuration option.

Is there some backwards-compat problem with that option in older versions of Redcarpet?

[lsegal]

@bclennox you can see my original reply for my stance on this. Patches are accepted, but none were made.

[bclennox]

@lsegal Ah, sorry. I just misread. I'll take a stab.

[akzhan]

Now tables are supported by newest YARD itself. More at #765.

[seanlinsley]

❤️