Previous: Write a Blog Post Up: 目次 Next: Translate Documentation

How-To - Write Documentation

This page was machine translated. Please help us improve it.

See How-To - Translate Documentation

Rubiniusのドキュメントは、Webサイトとブログで構成されています。他の部分と同じくJekyllを使用しています。

始めに、kramdownjekyllがインストールされていることを確かめてください。

rbx gem install jekyll kramdown

ドキュメントは、web/docのディレクトリにあります。 各言語のサブディレクトリには、翻訳されたドキュメントががあります。(例えば、enesなど)

翻訳毎に目次があります。(例えば、/web/doc/ja/index.markdown)。 ドキュメントの残りの部分は、どのように他のドキュメントとリンクが張ってあるかというYAMLの属性から成る単一のファイルです。 基本的に、ドキュメントは前後のドキュメントにリンクが張ってある双方向リストとみなせます。

ドキュメントのYAMLの属性は下記の通りです。

---
layout: doc_en
title: How-To - Write Documentation
previous: Write a Blog Post
previous_url: how-to/write-a-blog-post
next: Translate Documentation
next_url: how-to/translate-documentation
---

layoutは、どのレイアウトをjekyllが使用するか指定します。 layoutLANGは、ISO-639-2のdoc_LANGにしなければいけません。

titleは、ページの上部に表示されるドキュメントのタイトルを指定します。

previousprevious_url属性で、前のドキュメントのタイトルとリンクを指定します。 同様に、nextnext_url属性で、後のドキュメントのタイトルとリンクを指定します。

これらはドキュメントの閲覧を便利にする、再度ドキュメントを書くときに必要な作業量を削減するためです。

RubiniusのリポジトリにJekyllで生成したドキュメントとファイルがコミットされます。リポジトリをクローンしたら、Rubiniusをインストールする前かRubiniusのビルドに問題があるとき rake docsでドキュメントを閲覧することができます。

既存ドキュメントの編集

ドキュメントの最初のアウトラインが作成されています。 ドキュメントを書く必要がある話題がたくさんあります。

既に存在している話題にドキュメントを追加するかドキュメントを修正する場合:

  1. web/doc/LANGの下のファイルを開く。
  2. ドキュメントの追加または改善を行う。
  3. 作業中のドキュメントのアップデートを見る。 web/ディレクトリでrbx -S jekyll serve --watchを実行する。
  4. ドキュメントの追加または編集が終了したら、ソースコードの変更をコミットする。
  5. web/ディレクトリでrbx -S jekyll buildを実行し、web/_siteの全てのファイルを強制的にアップデートする。
  6. 生成したファイルをコミットする。変更が少ない場合、ドキュメントのソースコードと生成したファイルをコミットしてください。 変更が多い場合、レビューでの変更が単純になるように生成したファイルを個別にコミットしてください。

新しいドキュメントの追加

存在してない話題をのドキュメントを追加する場合:

  1. web/doc/LANGに.markdown拡張子のファイルを作成する。
  2. 既に存在してるファイルから新しいファイルにリンクを張るために属性を記述する。 index.markdownと既に存在しているファイルのpreviousnext attributesに新しいファイルへのリンクを記述することが必要です。
  3. 作業中にアップデートしたドキュメントを見るには、rbx -S jekyll serve --watchを実行します。
  4. マークダウン記法で新しいファイルを編集します。
  5. ドキュメントの追加または編集が終わったら、変更をコミットしてください。
  6. rbx -S jekyll build in the web/ を実行し、web/_siteで生成されているファイルを強制的にアップデートしてください。
  7. 生成したファイルをコミットする。変更が少ない場合、ドキュメントのソースコードと生成したファイルをコミットしてください。 変更が多い場合、レビューでの変更が単純になるように生成したファイルを個別にコミットしてください。
Previous: Write a Blog Post Up: 目次 Next: Translate Documentation

Tweet at @rubinius on Twitter or email community@rubini.us. Please report Rubinius issues to our issue tracker.