Рекомендации для руководств по Ruby on Rails

Это руководство документирует рекомендации по написанию руководств по Ruby on Rails. Это руководство следует самому себе в изящном цикле, являясь примером для самого себя.

После прочтения этого руководства вы узнаете:

• О соглашениях, используемых в документации Rails.
• Как генерировать руководства локально.

Markdown

Руководства написаны на GitHub Flavored Markdown. Имеется полная документация по Markdown, а также шпаргалка.

Пролог

Каждое руководство должно начинаться с мотивационного текста сверху (это маленькое введение в голубой области). Пролог должен рассказать читателю, о чём это руководство и что они изучат. В качестве примера смотрите руководство по роутингу.

Заголовки

Название каждого руководства использует заголовок 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?

Используйте такое же inline-форматирование, как и в обычном тексте:

##### The `:content_type` Option

Примеры кода

Оборачивайте примеры кода в синтаксис ограждений кода с использованием обратных кавычек:

```ruby
puts "Hello World!"
```

Всегда указывайте используемый в примере язык. Поддерживаемые ярлыки языков включают: ruby, html, irb, html+erb, bash и js.

```js
alert("Hello World!")
```

Имена файлов для примеров

Если пример ссылается на конкретный файл, добавьте имя файла в комментариях:

```ruby
# app/model/product.rb

class Product < ApplicationRecord
end
```

NOTE: Комментарии с именами файлов игнорируются кнопкой копирования.

Для шаблонов ERB используйте комментарии ERB:

```html+erb
<%# app/views/products/show.html.erb %>
<h1><%= @product.name %></h1>

<%= link_to "Back", products_path %>
```

Примеры с командной строкой

Для примеров bash используйте $ как символ приглашения:

```bash
$ cd my_app
$ bin/rails server
```

NOTE: Приглашения игнорируются кнопкой копирования.

Для примеров консоли Rails используйте application(environment)> как приглашение:

```ruby
store(dev)> Product.first
=> #<Product:0x00000001221f6260 id: 1, name: "T-Shirt", created_at: "2024-11-09 16:35:01.117836000 +0000", updated_at: "2024-11-09 16:35:01.117836000 +0000">
```

Подсветка кода

Для больших примеров небольшие изменения может быть сложно заметить. Подсветите строки, передав их номера:

```ruby#4,7-9
# app/model/product.rb

class Product < ApplicationRecord
  validates :name, presence: true
  validates :price, presence: true

  def back_in_stock?
    inventory_count_previously_was.zero? && inventory_count.positive?
  end
end
```

Это подсветит строку 4 и строки с 7 по 9:

# app/model/product.rb

class Product < ApplicationRecord
  validates :name, presence: true
  validates :price, presence: true

  def back_in_stock?
    inventory_count_previously_was.zero? && inventory_count.positive?
  end
end

Примечания, советы и предупреждения

Иногда абзац заслуживает чуть большего внимания. Например, чтобы разъяснить распространённое заблуждение или предупредить о чём-то, что может сломать приложение.

Чтобы выделить абзац, начните его с NOTE:, TIP: или WARNING::

NOTE: Используйте `NOTE`, `TIP` или `WARNING`, чтобы выделить абзац.

Это обернёт абзац в специальный контейнер с таким результатом:

NOTE: Используйте NOTE, TIP или WARNING, чтобы выделить абзац.

NOTE

Используйте NOTE, чтобы выделить что-то, относящееся к теме и контексту. Чтение этой пометки поможет вам понять данную тему или контекст или прояснит важный момент.

Например, раздел, описывающий файлы локалей, может содержать такое NOTE:

NOTE: Необходимо перезапустить сервер при добавлении новых файлов локалей.

TIP

TIP — это просто дополнительная информация по теме, но не обязательно существенная для понимания. Она может направить вас к другому руководству или сайту:

TIP: Чтобы узнать больше о роутинге, смотрите Роутинг в Rails извне внутрь.

Или показать полезную команду для просмотра дополнительных опций:

TIP: Для дополнительной помощи с генераторами выполните bin/rails generate --help.

WARNING

Используйте WARNING для того, чего следует избегать и что может сломать приложение:

WARNING: Воздерживайтесь от использования методов вроде update, save или любых других методов, вызывающих побочные эффекты на объекте, внутри ваших колбэк-методов.

Или предупредите о том, что может скомпрометировать безопасность приложения.

WARNING: Храните свой master key в безопасности. Не коммитьте свой master key.

Ссылки

Используйте описательные ссылки и избегайте ссылок "здесь" и "подробнее":

# ПЛОХО
См. документацию Rails Internationalization (I18n) API для [подробностей](i18n.html).

# ХОРОШО
См. [документацию Rails Internationalization (I18n) API](i18n.html) для
подробностей.

Используйте описательные ссылки и для внутренних ссылок:

# ПЛОХО
Мы рассмотрим это [ниже](#multiple-callback-conditions).

# ХОРОШО
Мы рассмотрим это в [разделе о нескольких условиях колбэка
](#multiple-callback-conditions) ниже.

Ссылки на API

Ссылки на API (api.rubyonrails.org) обрабатываются генератором руководств следующим образом:

Ссылки, включающие тег релиза, оставляются неизменными. Например

https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

не модифицируется.

Пожалуйста, используйте их в заметках о релизе, так как они должны указывать на соответствующую версию вне зависимости от генерируемого таргета.

Если ссылка не включает тег релиза и генерируются edge-руководства, домен заменяется на edgeapi.rubyonrails.org. Например,

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

становится

https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html

Если ссылка не включает тег релиза и генерируются руководства релиза, вставляется версия Rails. Например, если генерируются руководства для v5.1.0, ссылка

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

становится

https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html

Пожалуйста, не ссылайтесь на edgeapi.rubyonrails.org вручную.

Перенос колонок

Не переформатируйте старые руководства просто ради переноса колонок. Но новые разделы и руководства должны переноситься на 80 колонках.

Рекомендации по документированию API

Руководства и API должны быть согласованы и последовательны, насколько это уместно. В частности, эти разделы Рекомендаций по документированию API также применяются к руководствам:

• Формулировки
• Английский язык
• Пример кода
• Имена файлов
• Шрифты

Руководства в HTML

До генерации руководств убедитесь, что в вашей системе установлена последняя версия 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

Генерация

Чтобы сгенерировать руководства для Kindle, используйте следующую rake-задачу:

$ bundle exec rake guides:generate:kindle