La documentación de Rubinius está integrada con el sitio web y el blog. Utiliza Jekyll al igual que los otros componentes.
Para empezar, asegúrate de tener las gemas kramdown
y jekyll
instaladas.
rbx gem install kramdown jekyll
Los fuentes de la documentación se encuentran en el directorio web/doc
. Hay
subdirectorios por cada idioma para el cual la documentación ha sido traducida
(por ejemplo en
, es
, etc.)
Hay una Tabla de Contenido para cada traducción (por ejemplo
web/doc/es/index.markdown
). El resto de la documentación consiste en
archivos individuales que tienen atributos YAML para especificar cómo se
están conectados los documentos. Esencialmente, la documentación puede ser
vista como una lista doblemente enlazada de documentos, con cada documento
apuntando al anterior y al siguiente. El documento Tabla de Contenido
muestra la estructura completa.
Los atributos YAML en un documento se ven como como los siguientes:
---
layout: doc_es
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
---
El layout especifica a Jekyll que diagramación utilizar cuando se formatee
el documento. El layout debe ser doc_LANG
, donde LANG es el código
ISO-639-2 para el idioma.
El title especifica el título del documento que se muestra en la parte superior de la página.
Los atributos previous y previous_url dan el título y el vínculo al documento anterior. Del mismo modo, los atributos next y next_url dan el título y el vínculo para el próximo documento. Éstos se utilizan para mejorar la navegación de la documentación, limitando la cantidad de trabajo necesario para reordenar partes de ésta.
Tanto los fuentes de la documentación como los archivos generados por Jekyll
son subidos al repositorio de Rubinius. Cuando las personas clonan el
repositorio de Rubinius, pueden ejecutar rake docs
para ver la documentación
antes de compilar Rubinius o si tienen problemas en la compilación.
Un primer esbozo de la documentación ya ha sido creado. Hay muchos temas que simplemente necesitan que se escriba documentación para ellos.
Para agregar documentación a un tema existente o para corregir documentación existente:
web/doc/LANG
.rbx -S jekyll --server --auto
rbx -S jekyll
en el directorio web/
para forzar la
actualización de todos los archivos generados en web/_site
.Para agregar documentación para la cuál no existe un tema:
web/doc/LANG
.index.markdown
.rbx -S jekyll --server --auto
rbx -S jekyll
en el directorio web/
para forzar la
actualización de todos los archivos generados en web/_site
.