Dienstag, 8. September 2015

Aufbau eines lokalen Wiki für technische Dokumentation

Nachtrag: Ich habe inzwischen DocBook XML als die wesentliche bessere Möglichkeit entdeckt (siehe entsprechender Blogeintrag).
Ich lasse den Artikel aber einfach mal so stehen.



Auf der Suche nach einer soliden Basis zur Erstellung technischer Dokumentationen für Kunden-Systeme habe ich mir MediaWiki genauer angeschaut. MediaWiki ist das System welches auch hinter Wikipedia steckt. Es steht unter der GNU2 Lizenz zur Verfügung.

MediaWiki bietet folgende Vorteile für die Dokumentation:

  1. Leistungsfähige Web-Schnittstelle zur Recherche in der Dokumentation. Da so gut wie alle Leute Wikipedia kennen fällt die Navigation leicht.
  2. Dokumentation kann in Artikel aufgeteilt werden und ist dennoch zentral verfügbar.
  3. MediaWiki Installation kann lokal beim Kunden eingerichtet werden, so dass die Dokumentation nur intern abgerufen werden kann
  4. Es können mehrere Nutzer an der Dokumentation arbeiten
  5. Versionierung wird unterstützt.
  6. Schlankes System dass auf einer kleinen VM installiert werden kann
  7. Einfaches Backup der dahinterstehenden MySQL Datenbank
  8. Buch-Funktion: Aus dem Wiki kann ein buch-ähnliches PDF mit Inhaltsverzeichnis, Seitenzahlen usw. erzeugt werden. Dazu später mehr.

Buchfunktion


Erfahrungsgemäß möchten Kunden eine Druckversion der Doku oder zumindest ein ordentlich aufbereitetes PDF haben. Dies macht Sinn, denn was nützt bei einem Ausfall der IT eine Dokumentation, die sich auf dem ausgefallen System befindet.
MediaWiki bietet die Möglichkeit, verschiedene Artikel zu einem Buch zusammen zu führen. Auf wikipedia.de kann man das einfach ausprobieren:

  1. www.wikipedia.de aufrufen und einen Artikel aufrufen (z.B. Münchehofe).
  2. Im Menübereich (links) im Bereich Drucken/exportieren auf Buch erstellen klicken.
  3. Auf der nächsten Seite Buchfunktion starten klicken
  4. Man gelangt wieder zum Artikel und kann am Ende der Seite im Bereich Buchgenerator die Seite zum Buch hinzufügen
  5. Man kann auf diese Weise beliebig viele Artikel zum Buch hinzufügen
  6. Sobald alle Artikel hinzugefügt sind klickt man im Bereich Buchgenerator auf Buch zeigen.
  7. Dort kann man Titel und Untertitel festlegen, zwischen 1- oder 2-spaltigem Layout wählen und die Reihenfolge der Artikel ändern (mit der Maus verschieben).
  8. Im Bereich Herunterladen kann die Erstellung einer PDF-Version anstoßen. Diese steht kurze Zeit später zum Download bereit.
Einfach mal probieren. Das PDF sieht wirklich gut aus. Inhaltsverzeichnis, Teilüberschriften, Bilder, Quellen - alles ist drin. Das kann man schon abgeben.

Wer heute also eine Plagiatsarbeit abgeben möchte, klickt die Artikel einfach bei Wikipedia zusammen und macht gleich ein Buch daraus - fertig ;)

Lokale Installation


Eine lokale Mediawiki-Installation ist in einer Linux-Apache-MySQL-PHP Umgebung in wenigen Minuten startklar. Darauf gehe ich nicht weiter ein. Mehr hier:


Man wird aber schnell feststellen, dass der Buchgenerator fehlt. Diesen lokal zum Laufen zu bekommen empfand ich als relativ schwierig.

Ich habe 2 Möglichkeiten zur Erstellung von Büchern aus einem Wiki gefunden:

  1. Über Collection extension, Parsoid-Service und den Offline Content Generator (OCG): Diese Variante wird von wikipedia.org und wikipedia.de eingesetzt und scheint der in Zukunft favorisierte Weg zu sein. Kapitel und Teilüberschriften werden durchnummeriert und man kann zwischen 1- oder 2-spaltigem Seitenlayout wählen.
  2. Über Collection extension und mwlib von PediaPress: Kapitel und Teilüberschriften werden nicht durchnummeriert und es wird nur das 1-spaltige Layout unterstützt.

Installation Collection extenstion


Die Collection extension wird für beide Varianten benötigt. Diese ermöglicht das Sammeln der Artikel und erweitert die Wiki-Oberfläche um die Buchfunktion.

Installation der Collection extension:
https://www.mediawiki.org/wiki/Extension:Collection#Installation

Das Einbinden der extension geschieht in der LocalSettings.php im mediawiki Hauptverzeichnis:

require_once "$IP/extensions/Collection/Collection.php";


Je nach genutzter Variante (Parsiod+OCG oder mwlib) müssen noch weitere Anpassungen in der LocalSettings.php erfolgen (mehr nachfolgend).


Variante 1: Parsoid-Service und OCG


Zusätzlich zur Collection extension müssen folgende Dinge installiert werden:
  1. Offline Content Generator (OCG) bundler: Der bundler packt die gesammelten Artikel inklusive der Bilder usw. in ein ZIP-Archiv.
    Die Inhalte werden dabei als JSON bzw. SQLLite Datenbankdateien abgelegt.
  2. OCG-latexer: Der ocg-latexer erstellt aus dem vom ocg-bundler gelieferten Archiv mit Hilfe von Latex ein PDF Dokument
  3. OCG-service: Der ocg-service stellt einen Server bereit, der ocg-bundler und ocg-latexer steuert. Die Collection extension stellt eine Verbindung mit dem ocg-service her, um die PDF-Erzeugung anzufordern.
  4. Parsoid Service: Der ocg-bundler benötigt entweder eine Parsoid-Service oder ein RESTFUL-API, um die Daten aus der MediaWiki Installation abzufragen. Ich habe den Parsoid Service verwendet. Dieser stellt ein API für den Zugriff auf das Wiki zur Verfügung.
Für eine einfache lokale Installation ist das ganz schön aufwändig. Die ganze Sache zum Arbeiten zu überreden ist ebenfalls nicht ganz einfach.

Die Installation der OCG-Komponenten ist hier beschrieben:

http://wikitech.wikimedia.org/wiki/OCG

Konfigurieren und Starten des OCG-Service


Das Wiki stellt eine Verbindung mit dem OCG-Service her, um die gewählten Artikel in ein PDF zu bringen. Damit das funktioniert, muss der OCG-Service gestartet werden.
Der OCG-Service nutzt wiederum den Parsoid Service. Standardmäßig wird der online verfügbare Wikipedia Parsoid-Service genutzt, der aber natrürlich keinen Zugriff auf ein lokal installiertes Wiki hat.
Daher muss vor Starten des OCG-Service im Verzeichnis mw-ocg-service ein Konfigurationsdatei localsettings.php mit folgendem Inhalt erstellt werden:

module.exports = function(config) {
  // host + port where PARSOID is running
  config.backend.bundler.parsoid_api = "http://localhost:8000";
  // the prefix here should match $wgDBname in your LocalSettings.php
  config.backend.bundler.parsoid_prefix = "localhost";
  // Use the Parsoid "v3" API
  config.backend.bundler.additionalArgs = [ '--api-version=parsoid3' ];
}

Beim Start des OCG-Service wird mit der Option -c die Konfigurationsdatei angegeben:

peter@gorgonzola:~$ ./mw-ocg-service.js -c localsettings.js

Der OCG-Service sollte danach ohne Fehlermeldungen hochfahren.


Konfigurieren und Starten des Parsoid Service


Ich habe Parsoid aud dem GIT Repository geholt und eingerichtet:
https://www.mediawiki.org/wiki/Parsoid/Developer_Setup

Die Installation des Parsoid Service aus einem Ubuntu Repo wird hier beschrieben:
https://www.mediawiki.org/wiki/Parsoid/Setup


Wie im Developer Setup beschrieben habe ich die Datei api/localsettings.js aus der Vorlagedatei erstellt und ungepasst.

Der Start des Parsoid Service erfolgt über:

peter@gorgonzola:~$ node api/server.js

Der Dienst muss ohne Fehlermeldungen hochfahren.

Anpassen der LocalSettings.php

Im  mediawiki Hauptverzeichnis müssen noch folgende Zeilen in der LocalSettings.php am Ende ergänzt werden:

$wgCollectionFormatToServeURL['rdf2latex'] =
$wgCollectionFormatToServeURL['rdf2text'] = 'http://localhost:17080';

// MediaWiki namespace is not a good default
$wgCommunityCollectionNamespace = NS_PROJECT;

// Sidebar cache doesn't play nice with this
$wgEnableSidebarCache = false;

$wgCollectionFormats = array(
    'rdf2latex' => 'PDF',
        'rdf2text' => 'Plain text',
);
 
$wgLicenseURL = "http://creativecommons.org/licenses/by-sa/3.0/";
$wgCollectionPortletFormats = array( 'rdf2latex', 'rdf2text' );
Damit wird der OCG-Service in die Wiki-Oberfläche eingebunden (localhost:17080).

Probleme mit Bildern


Ich hatte zunächst Probleme mit den eingebundenen Bildern. Diese werden im Wiki-Artikel in der Regel so eingebunden:

[[Datei:Bild.jpg|mini|Bildtitel]]

Entscheidend ist die Größenangabe mini. Ohne diese wird das Bild 1:1 mit 72dpi in das PDF aufgenommen und ragt entweder aus dem Dokument heraus (bei höher aufgelösten Bildern) oder ist unscharf (bei kleinen Bildern).

Mit der Größenangabe mini hatte ich zunächst das Problem, dass die Bilder gar nicht mehr im PDF auftauchten.
Nach intensiver Suche habe ich herausgefunden, dass der OCG die Bilder mit der Größe mini in einer Breite (Auflösung) von 1200px anfordert. Wenn die Bilder nicht in dieser Auflösung vorliegen, bekommt der OCG anstelle des Bildes einen HTML 404 und diese Textdatei kann im weiteren Verlauf der Verarbeitung nicht in das PDF eingebunden werden.

Fürs erste lade ich also alle Bilder mit width=1200px hoch.


Variante 2: PediePress mwlib


Habe ich mir nicht mehr angeschaut.


Fazit

Die Buchfunktion ist eine schöne Sache. Allerdings ist das Aufsetzen kompliziert. Einige Dinge (wie z.B. Tabellen) werden nicht dargestellt.
Ausserdem bleibt das Problem, dass ein Wiki kein Inhaltsverzeichnis besitzt. Es handelt sich um eigenständige Artikel, die zur Erstellung eines Buches immer in einer bestimmten Reihenfolge zusammengestellt werden müssen.

Ich habe weiter gesucht und inzwischen DocBook XML als die für meine Zwecke bessere Variante entdeckt (siehe entsprechender Blog Artikel).

Keine Kommentare:

Kommentar veröffentlichen