当前位置: 首页>>代码示例 >>用法及示例精选 >>正文

Ruby Markup类用法及代码示例


本文简要介绍ruby语言中 RDoc::Markup类 的用法。

RDoc::Markup 解析纯文本文档并尝试将它们分解为其组成部分。其中一些部分是高级的：段落、逐字文本块、列表条目等。其他部分发生在字符级别：一段粗体文本，一个代码字体的单词。这种标记在精神上与WikiWiki 网站上使用的标记相似，人们使用一组简单的格式规则创建网页。

RDoc::Markup 和其他标记格式不进行输出格式化，这由 RDoc::Markup::Formatter 子类处理。

支持的格式

除了 RDoc::Markup 格式之外，RDoc 还内置了以下格式：

降价

daringfireball.net/projects/markdown /说明的降价格式。有关解析器和支持的扩展的详细信息，请参阅 RDoc::Markdown 。

rd

rdtool 格式。有关解析器和格式的详细信息，请参阅 RDoc::RD 。

tomdoc

tomdoc.org /说明的 TomDoc 格式。有关解析器和支持的扩展的详细信息，请参阅 RDoc::TomDoc 。

您可以使用以下方法选择标记格式：

每个项目

如果您使用 rake 构建文档，请使用 RDoc::Task#markup 。

如果您手动构建文档：

rdoc --markup your_favorite_format --write-options

并提交 .rdoc_options 并将其与打包的 gem 一起发布。

每个文件

在文件的顶部，使用:markup: 指令为文件的其余部分设置默认格式。

每条评论

在要以不同格式编写的注释顶部使用 :markup: 指令。

RDoc::Markup

RDoc::Markup 在运行时可扩展：您可以添加新的标记元素以在 RDoc::Markup 解析的文档中被识别。

RDoc::Markup 旨在成为一系列工具的基础，这些工具具有以下共同要求：简单的 plain-text 应该以各种不同的输出格式和媒体呈现。设想 RDoc::Markup 可以作为格式化 RDoc 样式评论块、Wiki 条目和在线常见问题解答的基础。

概要

此代码将 input_string 转换为 HTML。转换发生在convert 方法中，因此您可以使用相同的 RDoc::Markup 转换器来转换多个输入字符串。

require 'rdoc'

h = RDoc::Markup::ToHtml.new(RDoc::Options.new)

puts h.convert(input_string)

您可以扩展 RDoc::Markup 解析器以识别新的标记序列，并添加正则表达式处理。在这里，我们使WikiWords 对解析器有意义，并使序列 {word} 和 text... 表示 strike-through 文本。然后我们子类化 HTML 输出类来处理这些：

require 'rdoc'

class WikiHtml < RDoc::Markup::ToHtml
  def handle_regexp_WIKIWORD(target)
    "<font color=red>" + target.text + "</font>"
  end
end

markup = RDoc::Markup.new
markup.add_word_pair("{", "}", :STRIKE)
markup.add_html("no", :STRIKE)

markup.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)

wh = WikiHtml.new RDoc::Options.new, markup
wh.add_tag(:STRIKE, "<strike>", "</strike>")

puts "<body>#{wh.convert ARGF.read}</body>"

Encoding

在 Encoding 支持可用的情况下， RDoc 将自动将所有文档转换为相同的输出编码。输出编码可以通过 RDoc::Options#encoding 设置，默认为 Encoding.default_external 。

RDoc Markup 参考

块 Markup

段落和逐字

标记引擎查找文档的自然左边距。这用作文档的初始边距。

从此页边距开始的连续行被视为一个段落。空行分隔段落。

从当前页边距右侧开始的任何行都被视为逐字文本。这对于代码清单很有用：

3.times { puts "Ruby" }

在逐字文本中，两个或多个空行合并为一个，并删除尾随空行：

This is the first line

This is the second non-blank line,
after 2 blank lines in the source markup.

本段正上方有两个尾随空行，已被删除。此外，逐字文本已向左移动，因此逐字文本的缩进量并不重要。

对于 HTML 输出， RDoc 会稍微确定逐字部分是否包含 Ruby 源代码。如果是这样，逐字块将被标记为 HTML。触发器包括“def”, “class”, “module”, “require”、“hash rocket”# (=>) 或带参数的块调用。

标头

以等号 (=) 开头的行被视为标题。一级标题有一个等号，二级标题有两个等号，依此类推，直到六级，这是最大值(七个连字符或更多连字符导致六级标题)。

例如，上面的标头是通过以下方式获得的：

=== Headers

在 HTML 输出标头中有一个与其名称匹配的 id。上面例子的 HTML 是：

<h3 id="label-Headers">Headers</h3>

如果标题在方法体内，则 id 将以方法的 id 为前缀。如果上面的标头在文档中的某个方法的位置，例如：

##
# This method does fun things
#
# = Example
#
#   Example of fun things goes here ...

def do_fun_things
end

标头的 id 将是：

<h1 id="method-i-do_fun_things-label-Example">Example</h1>

标签可以是 linked-to 使用 SomeClass@Headers 。有关详细信息，请参阅Links。

规则

以三个或更多连字符开头的行(在当前缩进处)生成水平线。

---

产生：

简单列表

如果段落以“*”、“-”、“<digit>.” 或“<letter>.” 开头，则将其视为列表的开头。边距增加到列表开始标志后面的第一个非空格。后续行应该缩进到这个新的边距，直到列表结束。例如：

* this is a list with three paragraphs in
  the first item.  This is the first paragraph.

  And this is the second paragraph.

  1. This is an indented, numbered list.
  2. This is the second item in that list

  This is the third conventional paragraph in the
  first list item.

* This is the second item in the original list

产生：

  • 这是第一项中包含三个段落的列表。这是第一段。

    这是第二段。

    1. 这是一个缩进的编号列表。

    2. 这是该列表中的第二项

    这是第一个列表项中的第三个常规段落。

  • 这是原始列表中的第二项

标记列表

您还可以构建带标签的列表，有时称为说明或定义列表。通过将标签放在方括号中并缩进列表主体来做到这一点：

[cat]  a small furry mammal
       that seems to sleep a lot

[ant]  a little insect that is known
       to enjoy picnics

产生：

cat

一种毛茸茸的小哺乳动物，似乎经常睡觉

蚂蚁

一种以喜欢野餐着称的小昆虫

如果您希望列表主体与标签左侧对齐，请使用两个冒号：

cat::  a small furry mammal
       that seems to sleep a lot

ant::  a little insect that is known
       to enjoy picnics

产生：

cat

一种毛茸茸的小哺乳动物，似乎经常睡觉

蚂蚁

一种以喜欢野餐着称的小昆虫

请注意，标签后的空白行在标签列表中被忽略：

[one]

    definition 1

[two]

    definition 2

产生与

[one]  definition 1
[two]  definition 2

列表和逐字记录

如果你想在列表之后引入逐字部分，它必须比列表项正文缩进少，但比列表标签、字母、数字或项目符号缩进更多。例如：

*   point 1

*   point 2, first paragraph

    point 2, second paragraph
      verbatim text inside point 2
    point 2, third paragraph
  verbatim text outside of the list (the list is therefore closed)
regular paragraph after the list

产生：

  • 第 1 点

  • 第 2 点，第一段

    第 2 点，第二段

    verbatim text inside point 2

    第 2 点，第三段

verbatim text outside of the list (the list is therefore closed)

列表后的常规段落

文字 Markup

粗体、斜体、打字机文本

您可以在文本中使用标记(逐字除外)来更改该文本部分的外观。开箱即用， RDoc::Markup 支持基于单词和通用标记。

基于单词的标记在单个单词周围使用标志字符：

*word*

以粗体显示word

_word_

以emphasized 字体显示word

+word+

以code 字体显示word

一般标记会影响开始分隔符和结束分隔符之间的文本。毫不奇怪，这些分隔符看起来像 HTML 标记。

<b>text</b>

以粗体显示text

<em>text</em>

以 emphasized 字体显示 text(替代标签：<i>)

<tt>text</tt>

以 code 字体显示 text(替代标签：<code>)

与传统的 Wiki 标记不同，通用标记可以跨越行边界。您可以通过在第一个字符前加上反斜杠来关闭标记的解释(参见下面的Escaping Text Markup)。

可以识别以 http: 、 https: 、 mailto: 、 ftp: 或 www. 开头的链接。引用外部图像的 HTTP url 被转换为内联图像元素。

类和方法将自动链接到它们的定义。例如，RDoc::Markup 将链接到此文档。默认情况下，只有包含_ 的方法才会自动链接(所有方法都可以通过--hyperlink-all 命令行选项自动链接)。

Single-word 方法可以通过对实例方法使用# 字符或对类方法使用:: 字符来链接。例如，#convert 链接到 convert 。可以像 RDoc::Markup#convert 一样组合类或方法。

文档中的标题可以通过跟随类或方法来链接@然后是标题名称。RDoc::Markup@Links将链接到此部分，如下所示：RDoc::Markup 处的链接.包含多个单词的标题中的空格必须用+像RDoc::Markup@Escaping+Text+Markup.标点符号和其他特殊字符必须像CGI::Util.escape.

@ 也可用于链接到部分。如果一个部分和一个标题具有相同的名称，则该部分是链接的首选。

链接也可以是 label[url] 的形式，在这种情况下，显示的文本中使用 label，并且使用 url 作为目标。如果 label 包含多个单词，请将其放在大括号中：{multi word label}[url] 。 url 可以是带有标签的类、模块或方法的http: -type 链接或cross-reference。

使用 rdoc-image: 方案的链接将为 HTML 输出创建一个图像标记。仅支持完全限定的 URL。

rdoc-ref: 方案的链接将链接到引用的类、模块、方法、文件等。如果引用的项目不存在，则不会生成链接，并且将从结果文本中删除 rdoc-ref:。

以 rdoc-label:label_name 开头的链接将链接到 label_name 。您可以通过为当前链接提供名称(如rdoc-label:label-other:label-mine)来为当前链接(用于双向链接)创建标签

以link: 开头的链接是指其路径相对于--op 目录的本地文件。使用 rdoc-ref: 而不是 link: 链接到由 RDoc 生成的文件，因为链接目标在 RDoc 生成器中可能不同。

示例链接：

https://github.com/ruby/rdoc
mailto:user@example.com
{RDoc Documentation}[http://rdoc.rubyforge.org]
{RDoc Markup}[rdoc-ref:RDoc::Markup]

转义文本 Markup

文本标记可以用反斜杠转义，如 中一样，它是通过 \<tt> 获得的。除了在逐字部分和 标记之间，要生成反斜杠，您必须将其加倍，除非它后跟空格、制表符或换行符。否则，HTML 格式化程序将丢弃它，因为它用于转义潜在链接：

* The \ must be doubled if not followed by white space: \\.
* But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
* This is a link to {ruby-lang}[www.ruby-lang.org].
* This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org].
* This will not be linked to \RDoc::RDoc#document

生成：

  • 如果后面没有空格，则 \ 必须加倍：\。

  • 但不在 标签中：在 Regexp 中，\S 匹配非空格。

  • 这是ruby-lang的链接

  • 但是，这不是链接：{ruby-lang.org}[www.ruby-lang.org]

  • 这不会链接到 RDoc::RDoc#document

在 标记内，更准确地说，前导反斜杠仅在后跟标记字符 (<*_+)、反斜杠或已知链接引用(已知类或方法)时才会被删除。所以在上面的例子中，如果当前上下文中有一个名为S的类或模块，那么\S的反斜杠将被删除。

此行为继承自 RDoc 版本 1，并已保留以与现有的 RDoc 文档兼容。

字符转换

HTML 会将两个/三个破折号转换为em-dash。其他常见字符也被转换：

em-dash::  -- or ---
ellipsis:: ...

single quotes:: 'text' or `text'
double quotes:: "text" or ``text''

copyright:: (c)
registered trademark:: (r)

产生：

em-dash

- 或者 -

省略

…

单引号

‘text’ 或 ‘text’

双引号

“text” 或 “text”

版权

©

注册商标

®

记录源代码

可以很自然地编写注释块，或者在注释的连续行上使用#，或者在=begin /=end 块中包含注释。如果您使用后一种形式，=begin 行 must 将被标记为 rdoc 标签：

=begin rdoc
Documentation to be processed by RDoc.

...
=end

RDoc 如果在 # 字符之后发现以 -- 开头的注释行，则停止处理注释(否则，如果它具有三个或更多破折号，它将被视为规则)。这可用于将外部注释与内部注释分开，或阻止注释与方法、类或模块相关联。可以使用以 ++ 开头的行重新打开注释。

##
# Extract the age and calculate the date-of-birth.
#--
# FIXME: fails if the birthday falls on February 29th
#++
# The DOB is returned as a Time object.

def get_dob(person)
  # ...
end

包含下划线或以井号字符开头的类、文件和任何方法名称的名称会自动从注释文本链接到它们的说明。此链接在当前类或模块内以及祖先方法(在包含的模块或超类中)有效。

Method 参数列表被提取并与方法说明一起显示。如果一个方法调用 yield ，那么传递给 yield 的参数也会被显示：

def fred
  ...
  yield line, address

这将被记录为：

fred() { |line, address| ... }

您可以在方法定义之后立即使用包含“：yields：...”的注释来覆盖它

def fred # :yields: index, position
  # ...

  yield line, address

这将被记录为

fred() { |index, position| ... }

:yields: 是文档指令的示例。它们在他们正在修改的文档元素开始后立即出现。

RDoc 自动 cross-references 带有下划线的单词或 camel-case。要禁止 cross-references，请在单词前面加上 \ 字符。要包含“\n”等特殊字符，您需要在普通文本中使用两个 \ 字符，但在 文本中只使用一个：

"\\n" or "<tt>\n</tt>"

产生：

“\n” 或“\n”

指令

指令是由“:” 字符包围的关键字。

控制记录的内容

:nodoc: /:nodoc: all

该指令防止生成元素的文档。对于类和模块，直接在受影响的类或模块中的方法、别名、常量和属性也将被省略。但是，默认情况下，该类或模块 will 中的模块和类会被记录。通过添加 all 修饰符可以关闭此函数。

module MyModule # :nodoc:
  class Input
  end
end

module OtherModule # :nodoc: all
  class Output
  end
end

在上面的代码中，只会记录类MyModule::Input。

:nodoc: 指令，如下面介绍的 :enddoc: 、 :stopdoc: 和 :startdoc: 是当前文件的本地指令：如果您不想记录出现在多个文件中的模块，请在每个外观上指定 :nodoc: ，每个文件至少一次。

:stopdoc: /:startdoc:

停止并开始向当前容器添加新的文档元素。例如，如果一个类有许多您不想记录的常量，则在第一个之前放置一个:stopdoc:，在最后一个之后放置一个:startdoc:。如果您未在容器末尾指定 :startdoc:，则会禁用当前文件其余部分的文档。

:doc:

强制记录方法或属性，即使它不会被记录。例如，如果您想包含特定私有方法的文档，则很有用。

:enddoc:

在当前级别不再记录：指令 :startdoc: 和 :doc: 将不会在当前文件中的当前容器(文件、类或模块)中得到遵守。

:notnew: /:not_new: /:not-new:

仅适用于initialize 实例方法。通常 RDoc 假定 initialize 的文档和参数实际上是用于 new 方法的，因此为该类伪造了一个 new。 :notnew: 指令会阻止这种情况。请记住，initialize 是私有的，因此除非您使用 -a 命令行选项，否则您不会看到文档。

Method 参数

:arg: 或 :args: parameters

使用这些参数覆盖默认参数处理。

##
#  :args: a, b

def some_method(*a)
end
:yield: 或 :yields: parameters

使用这些参数覆盖默认的产量发现。

##
# :yields: key, value

def each_thing &block
  @things.each(&block)
end
:call-seq:

直到下一个空行或注释中具有公共前缀的行被视为方法的调用序列，覆盖方法参数和产生参数的默认解析。

可以使用多条线路。

# :call-seq:
#   ARGF.readlines(sep=$/)     -> array
#   ARGF.readlines(limit)      -> array
#   ARGF.readlines(sep, limit) -> array
#
#   ARGF.to_a(sep=$/)     -> array
#   ARGF.to_a(limit)      -> array
#   ARGF.to_a(sep, limit) -> array
#
# The remaining lines are documentation ...

部分

节允许您将类中的方法分组到合理的容器中。如果您使用“Public”、“Internal”和“Deprecated”部分(TomDoc 中允许的三种方法状态)，这些部分将按该顺序显示，将最有用的方法放在顶部。否则，部分将按字母顺序显示。

:category: section

将此项目添加到命名的section，覆盖当前部分。使用它在 RDoc 输出中按部分对方法进行分组，同时保持合理的顺序(如字母顺序)。

# :category: Utility Methods
#
# CGI escapes +text+

def convert_string text
  CGI.escapeHTML text
end

空类别会将项目置于默认类别中：

# :category:
#
# This method is in the default category

def some_method
  # ...
end

与:section: 指令不同，:category: 不具有粘性。该类别仅适用于紧跟评论之后的项目。

使用:section: 指令为文档的一部分提供介绍性文本。

:section: title

在 RDoc 输出中提供部分介绍性文本。 :section: 后面的标题用作部分名称，包含该部分的注释的其余部分用作介绍性文本。一个部分的评论块必须与后面的评论块分开。使用空标题切换到默认部分。

:section: 指令是粘性的，因此后续的方法、别名、属性和类将包含在该部分中，直到该部分被更改。 :category: 指令将覆盖:section: 指令。

A:section: 注释块可能在:section: 指令之前有一行或多行。这些将被删除，并且块末尾的任何相同行也将被删除。这允许您向该部分添加视觉提示。

例子：

# ----------------------------------------
# :section: My Section
# This is the section that I wrote.
# See it glisten in the noon-day sun.
# ----------------------------------------

##
# Comment for some_method

def some_method
  # ...
end

其他指令

:markup: type

使用指定的标记类型覆盖此注释的默认标记类型。对于 Ruby 文件，如果第一个注释包含此指令，它将自动应用于文件中的所有注释。

除非您在标记格式之间进行转换，否则您应该使用.rdoc_options文件以指定整个项目的默认文档格式。看RDoc::Options 中保存的选项获取说明。

在文件的顶部，:markup: 指令适用于整个文件：

# coding: UTF-8
# :markup: TomDoc

# TomDoc comment here ...

class MyClass
  # ...

只需一条评论：

  # ...
end

# :markup: RDoc
#
# This is a comment in RDoc markup format ...

def some_method
  # ...

有关添加新标记格式的说明，请参阅标记中的贡献。

:include: filename

此时包括命名文件的内容。该指令必须单独出现在一行上，前面可能有空格。在这个位置，它可以在第一个冒号前用 \ 进行转义。

该文件将在 --include 选项列出的目录中搜索，默认情况下在当前目录中搜索。文件的内容将移动到与 :include: 指令开头的“:”相同的缩进。

:title: text

设置文档的标题。等效于--title 命令行参数。 (命令行参数覆盖源中的任何 :title: 指令)。

:main: name

等效于--main 命令行参数。

相关用法


注：本文由纯净天空筛选整理自ruby-lang.org大神的英文原创作品 Markup类。非经特殊声明，原始代码版权归原作者所有，本译文未经允许或授权，请勿转载或复制。