如何通过 Rake 将选项传递到 Yard 到 Kramdown 以使用 GFM答案

【问题标题】：How to pass options via Rake to Yard to Kramdown to use GFM如何通过 Rake 将选项传递到 Yard 到 Kramdown 以使用 GFM
【发布时间】：2015-06-14 04:07:00
【问题描述】：

我用一些用Github Flavoured markdown (GFM) 编写的文档制作了一个 gem，以利用它们的语法突出显示。

不幸的是，Github 决定使用他们自己的语法进行代码块屏蔽（三个反引号），以便让 Yardoc 正确解析我选择 Kramdown 作为解析器，supports GFM。

最重要的是，当我将代码推送到 Rubygems 时，将通过运行 Rake 任务生成文档（据我所知）。所以我需要找到一种方法，通过 Rake 告诉 Yard 使用 Kramdown GFM 解析器。

Kramdown 通过-i 开关选择解析器：

$ bin/kramdown --help

Command line options:

    -i, --input ARG
          Specify the input format: kramdown (default), html, GFM or markdown

但我不知道如何让 Yard 通过 yard 二进制文件或 Rake。我想这可以通过创建一个 Yardoc 插件来实现，但我从来没有这样做过，也不确定它是否会起作用，而且看起来事情到那时也会失控！

我真正喜欢的是一个降价标准，但这与其说是一个问题，不如说是一个未实现的愿望……我不确定 StackOverflow 是否能帮助解决这些问题。

对此的任何帮助将不胜感激。

【问题讨论】：

我们有一个similar issue with the Haml docs。当时我找不到任何友好的方式让 Yard 将选项传递给降价提供商（此后可能已经改变）。请注意，Github 还支持三重波浪号 (~~~) 以及用于防护代码块的三重反引号，因此您可以切换并改用该语法。
根据 changelog ，自 yardoc 版本 0.7.4 起，GFM 应该可以开箱即用。也许您可以为您的案例找到更多信息/想法here。
@matt 啊，我没有意识到他们也接受了这一点，这将是一个很好的权衡。谢谢。
@egwspit 信息量很大。我检查了 Rubygems，它已经正确渲染，只是无法让它在本地工作。安装 Redcarpet 在本地修复它。我无法让 Kramdown 开始工作，但现在我有 2 种选择，我不会出汗，谢谢 :)

标签： ruby rake yard kramdown

【解决方案1】：

我最近遇到了这个问题，并且在任何地方都找不到明确的指导，因此在深入研究了 Yard 的问题和来源之后，我想出了这种方法并且对它非常满意。希望它可能对遇到此线程的其他人有所帮助。

为 Yard 自定义添加一个 Ruby 文件。如果您在 docs/ 文件夹中有其他文档，那么 docs/yard_support.rb 可能是一个好地方。在其中，为 Yard 添加一个自定义标记提供程序。

# docs/yard_support.rb
require 'kramdown'
require 'kramdown-parser-gfm'

# Custom markup provider class that always renders Kramdown using GFM (Github
# Flavored Markdown). You could add additional customizations here, or even
# call a different Markdown library altogether, like `commonmarker`.
# The only requirement is that your class supports:
#   - `#initialize(markdown_text, options_hash)`
#   - `#to_html()`, which just returns the converted HTML source
class KramdownGfmDocument < Kramdown::Document
    def initialize(source, options = {})
        options[:input] = 'GFM' unless options.key?(:input)
        super(source, options)
    end
end

# Register the new provider as the highest priority option for Markdown.
# Unfortunately there's no nice interface for registering your provider; you
# just have to insert it directly at the front of the array. :\
# See also:
# - https://github.com/lsegal/yard/issues/1157
# - https://github.com/lsegal/yard/issues/1017
# - https://github.com/lsegal/yard/blob/main/lib/yard/templates/helpers/markup_helper.rb
YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].insert(
    0,
    { const: 'KramdownGfmDocument' }
)

在您的.yardopts 文件中使用--load <path_to_the_above_file>：
```
# .yardopts
--load docs/yard_support.rb
```

【讨论】：