RDoc記法の書き方(Rubyで使われるドキュメント記法)

2023年08月14日(月) Markdown

社内のナレッジ共有・マニュアル作成を成功させるツール「NotePM」→無料で使ってみる【1分で登録完了】

こんにちは。マニュアル作成・ナレッジ共有ツール「NotePM」ブログ編集局です。

Markdownが開発者の間では有名ですが、他にも記法は存在します。今回はその中の一つ、RDocの書き方を紹介します。RDocは特にRuby開発者の中では標準的なドキュメントフォーマットであり、Rubyソースコードの中に書くのに適したドキュメント記法です。

内容はRDoc Documentationに沿ったものとなっています。

 

 

リスト

リストは * または - を使います。数字のリストは行頭に数字 + ドットを付けます。

書き方の例です。

1
- 1-1
- 1-2
- 1-3
2
* 2-1
* 2-2
* 2-3
3
1. 3-1
2. 3-2
3. 3-3

これは次のように出力されます。見やすいように整形してあります。

<p>1</p>
<ul>
<li><p>1-1</p></li>
<li><p>1-2</p></li>
<li><p>1-3</p></li>
</ul>
<p>2</p>
<ul>
<li><p>2-1</p></li>
<li><p>2-2</p></li>
<li><p>2-3</p></li>
</ul>
<p>3</p>
<ol>
<li><p>3-1</p></li>
<li><p>3-2</p></li>
<li><p>3-3</p></li>
</ol>

定義リスト

dl/dt/ddを使った定義リストです。これは2パターン用意されています。

1
[]
[]

この場合は label-listクラスが付いています。

<p>1</p>
<dl class="rdoc-list label-list">
<dt>
<dd><p></p></dd>
<dt>
<dd><p></p></dd>
</dl>

次に :: を使った書き方があります。

3
::
::

こちらは note-list クラスになります。

<p>3</p>
<dl class="rdoc-list note-list">
<dt>
<dd><p></p></dd>
<dt>
<dd><p></p></dd>
</dl>

見出し

見出しは行頭に = を付けます。h1〜h6まで、= の数で指定します。

= 1
== 2

出力されるHTMLにはアンカーが追加されています。

<h1 id="label-E8-A6-8B-E5-87-BA-E3-81-971">
1
<span>
<a href="#label-E8-A6-8B-E5-87-BA-E3-81-971">&para;</a>
<a href="#top">&uarr;</a>
</span>
</h1>
<h2 id="label-E8-A6-8B-E5-87-BA-E3-81-972">
2
<span>
<a href="#label-E8-A6-8B-E5-87-BA-E3-81-972">&para;</a>
<a href="#top">&uarr;</a>
</span>
</h2>

水平線

- を3つ以上つなげるとhrタグになります。

---

文字装飾

文字装飾は次のようになります。

RDoc 内容
*文字* bタグ
_文字_ emタグ
+文字+ ttタグ

リンク

リンクは 文字[URL] で表現します。

Web NotePM[https://notepm.jp]

HTMLは次のように出力されます。

<p>Web <a href="https://notepm.jp">NotePM</a> </p>

コメント

コメントは -- ではじまり、 ++ が書かれるまでとなります。

--
++

HTMLは次のように出力されます。

<p></p>

まとめ

RDocはRubyのソースコード中に記述するのを想定しているため、あまり記法のパターンは多くありません。その代わりクラス名やメソッドなどを自動的にドキュメント内のリンクに展開するなど、コードを読み進める上で便利な機能もあります。普段RDocを使っている方は、READMEなどもRDocにすることでメンテナンスが容易になりそうです。

 

この資料でわかること

• 個人のノウハウを引き出す社内wikiとは?
• 社内wikiを導入し浸透させるために必要なこと
• 社内wikiツールの選び方

 

おすすめの情報共有ツール「NotePM」

NotePM

NotePM(ノートピーエム) は、Webで簡単にマニュアル作成できて、強力な検索機能でほしい情報をすぐに見つけられるサービスです。さまざまな業界業種に導入されている人気サービスで、大手IT製品レビューサイトでは、とくに『使いやすいさ・導入しやすさ』を高く評価されています。

NotePMの特徴

  • マニュアル作成、バージョン管理、社外メンバー共有
  • 強力な検索機能。PDFやExcelの中身も全文検索
  • 社内FAQ・質問箱・社内ポータルとしても活用できる
  • 銀行、大学も導入している高度なセキュリティ。安全に情報共有できる

URL: https://notepm.jp/

NotePMについて詳しく見る >