當前位置: 首頁>>編程示例 >>用法及示例精選 >>正文

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類。非經特殊聲明，原始代碼版權歸原作者所有，本譯文未經允許或授權，請勿轉載或複製。