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

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

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

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

1. Markdown

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

2. Пролог

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

3. Заголовки

Название каждого руководства использует заголовок h1; разделы руководства — заголовок h2; подразделы используют заголовок h3; и так далее. Отметьте, что сгенерированный в HTML результат будет использовать теги заголовков, начиная с <h2>.

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

Section
-------

### Sub Section

При написании заголовков начинайте с заглавной буквы все слова, кроме предлогов, союзов, внутренних артиклей и форм глагола "to be":

#### Middleware Stack is an Array
#### When are Objects Saved?

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

##### The `:content_type` Option

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

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

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

До генерации руководств, убедитесь, что используете последнюю версию Bundler в своей системе. На момент написания этих строк, вам нужно установить на свое устройство Bundler 1.3.5 или более поздний.

Чтобы установить последнюю версию Bundler, запустите gem install bundler.

5.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.

Также рекомендовано работать с WARNINGS=1. Это обнаружит дублированные ID и предупредит о битых внутренних ссылках.

Если хотите сгенерировать руководства на языке ином, чем английский, можете держать их в отдельной директории в source (то есть source/es) и использовать переменную среды GUIDES_LANGUAGE:

bundle exec rake guides:generate GUIDES_LANGUAGE=es

Если хотите увидеть все переменные окружения, которые могут использоваться генерационным скриптом, просто запустите:

rake

5.2. Валидация

Пожалуйста, проверяйте сгенерированный HTML с помощью:

bundle exec rake guides:validate

В частности, заголовки имеют ID, созданный на основе их содержания, и это часто ведет к дубликатам. Установите WARNINGS=1 при генерировании руководств, чтобы обнаружить их. Сообщение с предупреждением предложит решение.

6. Руководства для Kindle

6.1. Генерация

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

bundle exec rake guides:generate:kindle