How-To - Написание Документации - Rubinius
Author: Less Than Three. <3. http://less.thanthree.com
Description: Rubinius is an implementation of the Ruby programming language. The Rubinius bytecode virtual machine is written in C++. The bytecode compiler is written in pure Ruby. The vast majority of the core library is also written in Ruby, with some supporting primitives that interact with the VM directly.

1.2.3

## How-To - Написание Документации

Документация по 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` и сделайте это.

### Добавление новой документации

Проделайте следующее, чтобы добавить документацию для нового раздела:

1. Создайте в `web/doc/LANG` новый файл с расширение .markdown.
2. Установите атрибуты для связки нового файла с существующим. Это подразумевает редактирование previous и next атрибутов в уже существующих файлах.
3. Для просмотра изменений во время работы над ними, запустите `rbx -S jekyll --server --auto`
4. Отредактируйте новый файл с помощью синтаксиса Markdown.
5. В `web/` директории, выполните `rbx -S jekyll`.
6. Закомитьте все изменения в `web/` директории.