Docs header transparent bg

撰寫手冊頁面文件

此文件中的任何命令或檔案路徑都假設您在 rubygems/rubygems 存放庫的 bundler/ 目錄 中。

Bundler 使用者主要的求助來源是手冊頁面:執行 bundle help(或 bundler help)時印出的輸出。這些頁面的格式化和預覽可能有點棘手,但一旦上手後就相當簡單。

注意:bundlerbundle 可以互換使用於 CLI。本指南使用 bundle,因為它比較可愛。

手冊頁面中包含哪些內容?

我們使用手冊頁面來記載 CLI(命令列介面)中使用的 Bundler 命令。它們的長度可能從長(例如 bundle install)到非常短(例如 bundle clean)不等。

若要查看 Bundler CLI 中可用的命令清單,請輸入

  $ bundle help

我們的目標是為每個命令提供一個手冊頁面。

找不到某個命令的手冊頁面?建立一個新頁面並向我們發送 PR!我們也歡迎編輯現有的頁面。

建立新的手冊頁面

若要建立新的手冊頁面,只需在 lib/bundler/man/ 目錄中建立一個新的 .ronn 檔案。

例如:若要為命令 bundle cookies(很遺憾地,這不是一個真實的命令)建立一個手冊頁面,我會建立一個檔案 lib/bundler/man/bundle-cookies.1.ronn,並將我的文件新增到其中。

格式化

我們的手冊頁面使用 ronn 格式化,它是 Markdown 和標準手冊頁面慣例的組合。一開始可能有點不習慣,特別是如果您經常使用 Markdown 的話。

ronn 指南格式化指南 提供了常見格式化類型的良好概觀。

一般來說,讓您的頁面看起來像其他頁面:適當地使用 ##OPTIONS 等區段,以及程式碼區塊和定義清單等格式化。

如果您不確定格式是否正確,沒關係!提出一個包含您所擁有內容的 pull request,我們會仔細查看。

預覽

若要預覽變更,就像它們會列印出來供 Bundler 使用者使用,您需要執行一系列指令

$ rake spec:deps $ rake man:build $ man ./lib/bundler/man/bundle-cookies.1

如果您對 bundle-cookies.1.ronn 進行更多變更,您需要在預覽前再次執行 rake man:build

測試

我們對文件進行了測試!在您提出 pull request 之前,最重要的測試檔案是 help 指令的測試檔案,以及文件品質的測試檔案。

$ bin/rspec ./spec/commands/help_spec.rb $ bin/rspec ./spec/quality_spec.rb

撰寫 Bundler 文件網站 的文件

如果您想要提交 Bundler 文件網站 上任何主要指令或工具的 pull request,請遵循上述說明,從 rubygems/rubygems 儲存庫撰寫 man 頁面文件。在每種情況下,說明都是相同的。

注意:編輯 rubygems/rubygems 儲存庫中主要指令和工具文件的 .ronn 檔案,就是您需要做的 🎉。無需手動變更 rubygems/bundler-site 儲存庫中的任何內容,因為 Bundler 文件網站 上主要指令和工具的 man 頁面和文件是相同的。它們會自動從 rubygems/rubygems 儲存庫的 .ronn 檔案產生,透過 rake man:build 指令。

此外,如果您想要新增指南或教學課程:在 rubygems/bundler-site 儲存庫中,前往 /bundler-site/source/current_version_of_bundler/guides,並新增 新的 Markdown 檔案(副檔名為 .md)。務必正確格式化新指南的標題,如下所示: --- title: RubyGems.org SSL/TLS Troubleshooting Guide ---

如果您發現錯誤或發現有遺漏之處,請在 GitHub 上編輯此文件