Рекомендации для руководств по Ruby on Rails
Это руководство документирует рекомендации по написанию руководств по Ruby on Rails. Это руководство следует самому себе в изящном цикле, являясь примером для самого себя.
После прочтения этого руководства, вы узнаете:
- О соглашениях, используемых в документации Rails.
- Как генерировать руководства локально.
Markdown
Руководства написаны на GitHub Flavored Markdown. Имеется полная документация по Markdown, а также шпаргалка.
Пролог
Каждое руководство должно начинаться с мотивационного текста сверху (это маленькое введение в голубой области на официальном сайте). Пролог должен рассказать читателю, о чем это руководство, и что они изучат. В качестве примера смотрите Routing Guide.
Заголовки
Название каждого руководства использует заголовок 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
Связывание с API
Ссылки на API (api.rubyonrails.org) обрабатываются генератором руководств следующим образом:
Ссылки, включающие тег релиза, оставляются неизменными. Например
http://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html
не изменяется.
Пожалуйста, используйте их в заметках о релизе, так как они должны указывать на соответствующую версию, вне зависимости от генерирующейся версии.
Если ссылка не включает тег версии и генерируются руководства edge, домен заменяется на edgeapi.rubyonrails.org. Например,
http://api.rubyonrails.org/classes/ActionDispatch/Response.html
становится
http://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html
Если ссылка не включает тег релиза, и генерируются руководства релиза, вставляется версия Rails. Например, если генерируются руководства для v5.1.0, ссылка
http://api.rubyonrails.org/classes/ActionDispatch/Response.html
становится
http://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html
Пожалуйста, не ссылайтесь на edgeapi.rubyonrails.org вручную.
Рекомендации по документированию API
Эти руководства и API должны быть согласованны и последовательны, насколько возможно. В частности, эти разделы Рекомендаций по документированию API также применяются к руководствам:
Руководства в HTML
До генерации руководств, убедитесь, что используете последнюю версию Bundler в своей системе. На момент написания этих строк, вам нужно установить на свое устройство Bundler 1.3.5 или более поздний.
Чтобы установить последнюю версию Bundler, запустите gem install 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, сгенерированный на основе их содержания, и это часто ведет к дубликатам. Установите WARNINGS=1 при генерации руководств, чтобы обнаружить их. Сообщение с предупреждением предложит решение.
Руководства для Kindle
Генерация
Чтобы сгенерировать руководства для Kindle, используйте следующую задачу rake:
bundle exec rake guides:generate:kindle