如何让 Yardoc 输出到 STDOUT？

Question

我寻找了 gem 附带的模板（我只能找到默认的 HTML 输出器），我搜索了帮助和在线文档以找到将重定向到 STDOUT 的开关。我找不到任何关于如何解决这个问题的信息。

有没有一种简单的方法可以做到这一点（也许是 shell 命令？）或者我是否已经浏览了源代码？

Answer 1

• 创建以下文件test.rb：

  # This class is cool
  class Test
    # This method is also cool
    def foo
    end
  end
  

• 您必须先编译码文档，然后才能输出它。但您不想要该doc文件夹，对吧？所以我们忽略它。

  yardoc --no-output test.rb
  

  这只会更新.yardoc隐藏文件夹内的文档。doc不会生成该文件夹。

• 现在您可以通过几种方式查看特定对象的文档：

  > yard display "Test"
  # Outputs:
  ------------------------------------------ Class: Foo < Object
  
      This class is cool
  
  
  
  --------------------------------------------------------------
  
  > yard display "Test#foo"
  # Outputs:
  ------------------------------------------ Method: #meth (Foo)
                                            (Defined in: foo.rb)
  
      foo.meth -> Object
  --------------------------------------------------------------
  
      This method is cool
  

  这是您得到的输出。您可以使用该命令获取任何类/方法的院子文档yard display。

• 但是，嘿，输出很糟糕！让我们为其创建一个模板。创建以下templates包含几个文件的文件夹：

  + your app
    + templates
      + default
        + class
        | + text
        |   + setup.rb
        |       def init
        |         super
        |         sections T('docstring')
        |       end
        + method
        | + text
        |   + setup.rb
        |       def init
        |         super
        |         sections T('docstring')
        |       end
        + method_details
        | + text
        |   + setup.rb
        |       def init
        |         super
        |         sections T('docstring')
        |       end
  

  所有setup.rb文件必须具有相同的内容，例如def init, super, sections T('docstring'), end. 这将使text输出仅显示文档，而不显示任何花哨的标题和内容。

• 现在只需运行相同的yard display命令，但让我们使用自定义模板：

  > yard display Foo --template-path ./templates
  
  This class is cool
  
  > yard display "Foo#meth" --template-path ./templates
  
  This method is cool
  

• 就是这样。您可能会发现yard doc输出中可能有太多前导/尾随新行，您可以使用其他一些标准 Linuxhead/tail命令来修复该问题。