0

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

不幸的是，Github 决定使用他们自己的代码块屏蔽语法（三个反引号），以便让Yardoc正确解析，我选择了 Kramdown 作为解析器，它支持 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 插件来实现，但我从来没有这样做过，也不确定它是否会起作用，而且看起来事情在这一点上会失控！

我真正想要的是一个降价标准，但这与其说是一个未实现的愿望的问题......

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

4

1 回答 1

1

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

  1. 为 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' }
)

  2. --load <path_to_the_above_file>在您的.yardopts文件中使用：

    # .yardopts
--load docs/yard_support.rb
于 2020-09-01T07:53:14.357 回答