Назад: Написание сообщения в блог Выше: Содержание Вперед: Перевод документации

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 serve --watch
  4. Отредактируйте новый файл с помощью синтаксиса Markdown.
  5. В web/ директории, выполните rbx -S jekyll build.
  6. Закомитьте все изменения в web/ директории.
Назад: Написание сообщения в блог Выше: Содержание Вперед: Перевод документации

Tweet at @rubinius on Twitter or email community@rubini.us. Please report Rubinius issues to our issue tracker.