The Rubinius documentation is integrated with the website and blog. It uses Jekyll just like the other components.
To get started, ensure you have the kramdown
and jekyll
gems installed.
rbx gem install jekyll kramdown
The documentation source is under the web/doc
directory. There are
subdirectories for each language to which the documentation has been
translated (eg en
, es
, etc.).
There is a Table of Contents for each translation (e.g.
/web/doc/pt-br/index.markdown
). The rest of the documentation consists of
single files that have YAML attributes to specify how the documents are
connected. Essentially, the documentation can be viewed as a doubly-linked
list of documents with each document pointing to the previous and next
document. The Table of Contents document shows the complete structure.
The YAML attributes in a document look like the following:
---
layout: doc_en
title: How-To - Write Documentation
previous: Write a Blog Post
previous_url: how-to/write-a-blog-post
next: Translate Documentation
next_url: how-to/translate-documentation
---
The layout specifies which Jekyll layout to use when formatting the
document. The layout should be doc_LANG
, where LANG is the ISO-639-2
code for the language.
The title specifies the document title that is displayed at the top of the page.
The previous and previous_url attributes give the title and link to the previous document. Likewise, the next and next_url attributes give the title and link for the next document. These are used to enhance browsing the documentation and limiting the amount of work necessary to re-order parts of the documentation.
Both the source for the documentation and the files generated by Jekyll are
committed to the Rubinius repository. When people clone the source repository,
they can run rake docs
to view the documentation before they have built
Rubinius or if having problems building Rubinius.
An initial outline for the documentation has been created. There are many topics that merely need to have documentation written for them.
To add documentation for an existing topic or to fix existing documentation:
web/doc/LANG
.rbx -S jekyll --server --auto
in the web/
directory.rbx -S jekyll
in the web/
directory to force update of all
generated files in web/_site
.To add documentation for which no existing topic exists:
web/doc/LANG
.index.markdown
.rbx -S jekyll --server --auto
rbx -S jekyll
in the web/
directory to force update of all
generated files in web/_site
.