Using with .yardopts file

[topherfangio]

Hello, I'm very interested in getting yard-markdown working in my Ruby gem. I'm using a Docker setup and yard server --reload to watch for changes so that I can simply refresh the page.

I didn't realize Yard now supported Markdown out of the box using --markup markdown, but it doesn't seem to be as nice as what I'm hoping yard-markdown can do. In particular, I'm thinking about code blocks for examples and such.

However, I can't seem to get it working with .yardopts.

First Attempt

--debug
--output-dir docs/yard/generated
--plugin yard-markdown
--format markdown

With this approach, it seems to load the plugin just fine (there are no errors about it not being able to find it like if I do --plugin doesnotexist). However, I get the following error:

No such template for default/layout/markdown
/usr/local/bundle/gems/yard-0.9.36/lib/yard/templates/engine.rb:42:in `template'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/templates/engine.rb:84:in `render'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/code_objects/base.rb:508:in `format'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/commands/base.rb:147:in `render'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/commands/display_object_command.rb:30:in `run'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/commands/base.rb:97:in `call'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/commands/library_command.rb:74:in `block in call'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/commands/library_command.rb:91:in `call_without_fork'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/commands/library_command.rb:74:in `call'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/router.rb:141:in `route_docs'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/router.rb:115:in `route'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/router.rb:56:in `call'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/server/rack_adapter.rb:60:in `call'
/usr/local/bundle/gems/rack-2.2.9/lib/rack/handler/webrick.rb:95:in `service'
/usr/local/bundle/gems/webrick-1.8.1/lib/webrick/httpserver.rb:140:in `service'
/usr/local/bundle/gems/webrick-1.8.1/lib/webrick/httpserver.rb:96:in `run'
/usr/local/bundle/gems/webrick-1.8.1/lib/webrick/server.rb:310:in `block in start_thread'

Second Attempt

If I use --markup markdown, it appears to bypass it and use the built-in Markdown generator.

Third Attempt

If I add --markup-provider yard-markdown, I get the following error which I assume means your plugin doesn't define a custom markup provider:

undefined method `new' for nil
/usr/local/bundle/gems/yard-0.9.36/lib/yard/templates/helpers/html_helper.rb:95:in `html_markup_markdown'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/templates/helpers/html_helper.rb:62:in `htmlify'
/usr/local/bundle/gems/yard-0.9.36/templates/default/docstring/html/text.erb:3:in `_erb_cache_10'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/templates/template.rb:289:in `erb'
/usr/local/bundle/gems/yard-0.9.36/lib/yard/templates/template.rb:371:in `render_section'

Question

Am I missing something? Does it only work if you use the ~/.yard/config file?

Thanks!

[skatkov]

@topherfangio welcome to the world of trying to generate markdown documentation! It's a bit painful, but i'll try to give you as much support as possible here ;-)

Yard does have markdown support build in, but that's only for markup in your source code. Hence tweaking --markup=*** parameter doesn't really help here at all to produce markdown documentation.

No such template for default/layout/markdown error that you are seeing could mean two things.

1. You don't have yard-markdown gem installed. This is easy to check, with a following bash code gem list | grep yard.
2. Yard didn't detect or load yard-markdown plugin. This is a bit more complicated, I have noticed some flaky behavior here. In some cases, yard load_plugins could be disabled, in some cases plugin will not be loaded.

For me, the stable way to ensure that yard-markdown is always loaded is to define ~/.yard/config with the following contents:

!!!yaml
load_plugins: true
autoload_plugins:
  - markdown

I'm building an automated script, that tries to build markdown documentation from bunch of gems and this works 100% for me.

In your case, you might want to drop yard- from plugin name in .yardopts. e.g.

--debug
--output-dir docs/yard/generated
--plugin markdown
--format markdown

[skatkov]

Hopefully this answers your question. I'm closing this issue. You are welcome to suggest re-opening, if you feel that I can improve yard-markdown gem (maybe docs?)