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

Question

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

不幸的是，Github 决定使用他们自己的语法进行代码块防护（三个反引号），因此为了让 Yardoc 正确解析它，我选择了 Kramdown 作为解析器，它支持 GFM。

最重要的是，当我将代码推送到 Rubygems 时，将通过运行 Rake 任务来生成文档（据我所知）。所以我需要找到一种方法告诉 Yard 通过 Rake 使用 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 插件来实现，但我从来没有这样做过，不确定它是否会起作用，而且似乎那时事情会变得失控！

我真正想要的是一个降价标准，但这与其说是一个问题，不如说是一个未实现的愿望……我不确定 Stack Overflow 能在这些方面提供多大帮助。

Answer 1

添加用于 Yard 自定义的 Ruby 文件。如果您在
1. 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