更多資訊請參考 rubyonrails.org:

Ruby on Rails 指南規範

本指南說明撰寫 Ruby on Rails 指南的規範。本指南以優雅的循環方式遵循自身，並將自身作為範例。

閱讀本指南後，您將了解

  • 在 Rails 文件中使用的慣例。
  • 如何在本地產生指南。

1 Markdown

指南使用 GitHub Flavored Markdown 撰寫。有全面的 Markdown 文件，以及一份 速查表。

2 序言

每個指南都應該在頂部以激勵人心的文字開始（也就是藍色區域中的簡短介紹）。序言應該告訴讀者本指南的主題，以及他們將學到的內容。例如，請參閱路由指南。

3 標題

每個指南的標題都使用 h1 標題；指南章節使用 h2 標題；子章節使用 h3 標題；依此類推。請注意，產生的 HTML 輸出將使用從 <h2> 開始的標題標籤。

Guide Title
===========

Section
-------

### Sub Section

撰寫標題時，請將所有單字大寫，但介詞、連接詞、內部冠詞和動詞 "to be" 的形式除外。

#### Assertions and Testing Jobs inside Components
#### Middleware Stack is an Array
#### When are Objects Saved?

使用與一般文字相同的行內格式

##### The `:content_type` Option

4 注意事項、提示和警告

有時，一個段落值得更多的關注。例如，澄清常見的誤解或警告可能破壞應用程式的事項。

要強調一個段落，請在它前面加上 NOTE:、TIP: 或 WARNING:

NOTE: Use `NOTE`, `TIP` or `WARNING` to highlight a paragraph.

這會將段落包裝在一個特殊的容器中，產生以下結果

使用 NOTE、TIP 或 WARNING 來強調段落。

4.1 注意

使用 NOTE 來強調與主題和背景相關的事項。閱讀它將有助於您理解該主題或背景，或釐清重要項目。

例如，描述地區設定檔案的章節可以有以下 NOTE

當您新增新的地區設定檔案時，需要重新啟動伺服器。

4.2 提示

TIP 只是關於主題的額外資訊，但不一定與理解相關。它可以將您指向另一個指南或網站

要了解更多關於路由的資訊，請參閱 由外而內的 Rails 路由。

或顯示有用的命令以查看更多深入研究的選項

如需產生器的進一步協助，請執行 bin/rails generate --help。

4.3 警告

使用 WARNING 來表示應避免可能破壞應用程式的事項

請避免在您的回呼方法中使用類似 update、save 或任何其他會對物件造成副作用的方法。

或警告可能損害應用程式安全性的事項。

請妥善保管您的主金鑰。請勿提交您的主金鑰。

使用描述性連結，並避免「這裡」和「更多」連結

# BAD
See the Rails Internationalization (I18n) API documentation for [more
details](i18n.html).

# GOOD
See the [Rails Internationalization (I18n) API documentation](i18n.html) for
more details.

內部連結也請使用描述性連結

# BAD
We will cover this [below](#multiple-callback-conditions).

# GOOD
We will cover this in the [multiple callback conditions
section](#multiple-callback-conditions) shown below.

5.1 連結至 API

指南產生器會以下列方式處理指向 API (api.rubyonrails.org) 的連結

包含發行標籤的連結會保持不變。例如

https://rails-api.dev.org.tw/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

不會被修改。

請在發行說明中使用這些連結，因為無論產生的目標為何，它們都應該指向對應的版本。

如果連結不包含發行標籤，並且正在產生 edge 指南，則網域會被 edgeapi.rubyonrails.org 取代。例如，

https://rails-api.dev.org.tw/classes/ActionDispatch/Response.html

會變成

https://rails-api.dev.org.tw/classes/ActionDispatch/Response.html

如果連結不包含發行標籤，並且正在產生發行指南，則會插入 Rails 版本。例如，如果我們正在產生 v5.1.0 的指南，則連結

https://rails-api.dev.org.tw/classes/ActionDispatch/Response.html

會變成

https://rails-api.dev.org.tw/v5.1.0/classes/ActionDispatch/Response.html

請不要手動連結到 edgeapi.rubyonrails.org。

6 欄位換行

請勿僅為了換行而重新格式化舊指南。但是新的章節和指南應該在 80 個欄位處換行。

7 API 文件規範

指南和 API 應在適當情況下保持一致。特別是，API 文件規範的這些章節也適用於指南

8 HTML 指南

產生指南之前，請確保您的系統上已安裝最新版本的 Bundler。要安裝最新版本的 Bundler，請執行 gem install bundler。

如果您已經安裝了 Bundler，可以使用 gem update bundler 進行更新。

8.1 產生

要產生所有指南，只需 cd 進入 guides 目錄，執行 bundle install，然後執行

$ bundle exec rake guides:generate

或

$ bundle exec rake guides:generate:html

產生的 HTML 檔案可以在 ./output 目錄中找到。

要處理 my_guide.md 而不處理其他檔案，請使用 ONLY 環境變數

$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide

預設情況下，未修改的指南不會被處理，因此在實務上很少需要 ONLY。

要強制處理所有指南，請傳遞 ALL=1。

如果您想以英文以外的語言產生指南，您可以將它們保存在 source 下的單獨目錄中（例如 source/es），並使用 GUIDES_LANGUAGE 環境變數

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

如果您想查看所有可以用來設定產生腳本的環境變數，只需執行

$ rake

8.2 驗證

請使用以下命令驗證產生的 HTML

$ bundle exec rake guides:validate

特別是，標題會從其內容產生 ID，這通常會導致重複。

9 Kindle 指南

9.1 產生

要產生 Kindle 指南，請使用以下 rake 任務

$ bundle exec rake guides:generate:kindle
回到頂端