Документация по Rubinius интегрирована с веб-сайтом и блогом. Для нее также как и для других компонентов используется Jekyll.
Для начала убедитесь, что у вас установлены гемы kramdown
и jekyll
.
rbx gem install jekyll kramdown
Исходники документации расположены в директории web/doc
. Здесь присутствуют
поддиректории для существующих переводов на другие языки (например en
, es
).
Для кажого перевода присутствует содержание (напр.
/web/doc/ru/index.markdown
). Остальная часть документации состоит из
одиночных файлов, которые содержат YAML атрибуты для указания связи между
документами. Проще говоря, документацию можно представить как двусвязный
список документов, каждый из которых указывает на следующий и предыдущий.
Содержание показывает структуру документации в целом.
YAML атрибуты в документах имеют следующий вид:
---
layout: doc_ru
title: How-To - Написание документации
previous: Write a Blog Post
previous_url: how-to/write-a-blog-post
next: Перевод документации
next_url: how-to/translate-documentation
---
layout указывает на макет, который будет использовать Jekyll при
форматировании документа. layout должен соответствовать doc_LANG
, где
LANG это ISO-639-2 код языка.
title указывает заголовок документа, который отображается в начале страницы.
previous и previous_url представляют из себя название и ссылку на предыдущий документ. Точно также, next иnext_url соответствуют ссылке и названию следующего документа. Все это используется для повышения удобства просмотра документацию и сокращению размера работ необходимых для изменения порядка следования документов.
Существует первоначальная структура документации. Присутствует достаточно разделов, которые просто нуждаются в документировании.
Чтобы добавить документацию для существующих разделов или исправить ее,
откройте нужный файл в папке web/doc/LANG
и сделайте это.
Проделайте следующее, чтобы добавить документацию для нового раздела:
web/doc/LANG
новый файл с расширение .markdown.rbx -S jekyll --server --auto
web/
директории, выполните rbx -S jekyll
.web/
директории.