Ruby on Rails 指南準則 — Ruby on Rails 指南

1 Markdown

指南以 GitHub 風格 Markdown 撰寫。有全面的 Markdown 文件，以及秘笈。

每個指南應從頂端的激勵文字開始（藍色區域中的簡短引言）。序言應告訴讀者指南的內容，以及他們將學到什麼。例如，請參閱路由指南。

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

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

Section
-------

### Sub Section

撰寫標題時，除了介系詞、連接詞、內部冠詞和「be」動詞的形式以外，將所有字首字母大寫

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

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

##### The `:content_type` Option

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

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

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

不修改。

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

如果連結不包含發行標記，且正在產生邊緣指南，網域會被替換為 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。

不要重新格式化舊指南，只為了換行欄位。但新的章節和指南應在 80 個欄位處換行。

指南和 API 應在適當的地方保持一致且連貫。特別是，API 文件指南中的這些章節也適用於指南

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

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

若要產生所有指南，只要 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

請使用下列方式驗證產生的 HTML

$ bundle exec rake guides:validate

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

若要產生適用於 Kindle 的指南，請使用下列 rake 任務

$ bundle exec rake guides:generate:kindle

我們鼓勵您協助提升本指南的品質。

如果您發現任何錯字或事實錯誤，請協助我們修正。若要開始，您可以閱讀我們的文件貢獻區段。

您也可能會發現不完整或過時的內容。請務必加入任何主要文件中的遺漏文件。請務必先查看 Edge Guides 以驗證問題是否已在主要分支中修正。查看 Ruby on Rails 指南指南以了解風格和慣例。

如果您出於任何原因發現需要修正但無法自行修補的問題，請開啟問題。

最後但並非最不重要的一點，任何有關 Ruby on Rails 文件的討論都非常歡迎在官方 Ruby on Rails 論壇上進行。