Vorherige: Einen Blogeintrag schreiben Aufwärts: Inhaltsverzeichnis Nächste: Dokumentation übersetzen

Anleitung - Dokumentation schreiben

Die Dokumentation für Rubinius ist integriert mit der Website und dem Blog. Sie nutzt genau wie die übrigen Komponenten Jekyll.

Um zu starten, stelle sicher, dass du die kramdown und jekyll Gems installiert hast.

rbx gem install jekyll kramdown

Die Dokumentationsquellen befinden sich im web/doc Verzeichnis. Es existieren dort Unterverzeichnisse für alle Sprachen, die bereits in einer Übersetzung vorliegen (wie z.B. diese deutschen Übersetzung).

Jede Übersetzung besitzt ein Inhaltsverzeichnis (z.B. /web/doc/en/index.markdown). Der Rest der Dokumentation besteht aus einzelnen Dateien, die YAML Attribute benutzen, um anzugeben, wie die Dokumente zueinander in Beziehung stehen. Im Prinzip kann man die Dokumentation als eine doppelt verkettete Liste von Dokumenten verstehen, bei der jedes Dokument auf ein Vorgänger- sowie einen Nachfolgedokument verweist. Das Inhaltsverzeichnis zeigt dabei die komplette Struktur aller übrigen Dokumente an.

Die YAML Attribute in einem Dokument sehen in etwa wie folgt aus:

---
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
---

Das layout gibt an, welches Jekyll Layout bei der Formatierung des Dokuments genutzt werden soll. Das layout sollte doc_LANG entsprechen, wobei LANG ein ISO-639-1 Code für die Sprache ist (z.B. de, en, pl, es etc.).

Das title gibt den Dokumententitel an, der am oberen Rand der Seite dargestellt wird.

Die previous und previous_url Attribute stellen den Titel sowie Link zum vorherigen Dokument dar. Gleichermaßen entsprechen die next und next_url Attribute dem Titel und Link zum folgenden Dokument. Diese werden benutzt, um das Lesen und Durchstöbern der Dokumentation zu vereinfachen und den Arbeitsaufwand beim Neuordnen von Dokumentationsabschnitten zu minimieren.

Vorhandene Dokumentation bearbeiten

Ein anfänglicher Entwurf für die Dokumentation wurde bereits erstellt. Es gibt aber noch viele Themen, die einer vertiefenden Dokumentation bedürfen.

Um Dokumentation für ein bestehendes Thema hinzuzufügen oder vorhandene Dokumentation zu verbessern, öffne die Datei für das jeweilige Thema unter web/doc/LANG und füge dort neue Dokumentation hinzu oder überarbeite diese.

Neue Dokumentation hinzufügen

Um neue Dokumentation für bisher nicht dokumentierte Themen hinzuzufügen:

  1. Erstelle eine neue Datei mit der .markdown Dateiendung unter web/doc/LANG.
  2. Richte die YAML Attribute ein, sodass auf die neue Datei innerhalb der existierenden Dokumente verlinkt wird. Dies erfordert das Bearbeiten der previous and next Attribute der bereits vorhandenen Dateien, um die neue Datei einzufügen. Ebenso muss ein Eintrag in der index.markdown gemacht werden.
  3. Damit du Veränderungen noch beim Bearbeiten überprüfen kannst, führe folgenden Befehl aus und besuche die vom Server angegebene URL: rbx -S jekyll serve --watch
  4. Bearbeite die neue Datei mit dem Markdown Syntax.
  5. Im web/ Verzeichnis, führe rbx -S jekyll build aus.
  6. Mach ein Commit für alle Veränderungen im web/ Verzeichnis.
Vorherige: Einen Blogeintrag schreiben Aufwärts: Inhaltsverzeichnis Nächste: Dokumentation übersetzen

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