Warum funktioniert die mit Eclipse & Wolfram Workbench Plugin erstellte HTML-Hilfe nicht richtig?

Mit der Wolfram Workbench bzw. der Entwicklungsumgebung Eclipse und dem Wolfram Workbench Plugin kann man für eigene Mathematica-Applikationen eine Dokumentation erstellen, die sich nahtlos in das Mathematica Dokumentation Center integriert. Die Installation dieses Werkzeugs ist hier beschrieben.

Wie man damit eine Dokumentation für ein eigenes Projekt anlegt, ist hier in einem Video erklärt.

Die gleiche Dokumentation kann man anschließend auch als HTML-Dateien ausgeben lassen, die dann unabhängig von Mathematica lokal oder über einen Webserver bereitgestellt werden können.

Allerdings stellt man schnell fest, dass nach einem erfolgreichen Erstellen der HTML-Dokumentation diese zunächst "seltsam" aussieht und auch praktisch alle Links zu Symbolen, die durch den Benutzer definiert wurden, trotzdem auf die Webseiten des Herstellers (reference.wolfram.com) verlinken.

Damit die HTML-Hilfe sauber funktioniert, müssen zunächst die Styledateien an den richtigen Platz (von ...\build\package-HTML\HTML\standard nach ...\build\package-HTML\HTML) kopiert werden. Zusätzlich ist es nötig, die Links zu den eigenen Symbolen auf lokale relative Pfade zu korrigieren.

Dieser Vorgang kann bei einem großen Projekt sehr umständlich werden. Beschrieben ist diese Schwierigkeit unter anderem auf http://mathematica.stackexchange.com

Daher haben wir für Sie ein Beispielprojekt angelegt, das eine Post-Prozess-Funktion bereitstellt. Diese kopiert die nötigen Styledateien und behebt das Problem mit den lokalen Links.

Die ZIP-Datei kann direkt in die Workbench importiert werden (File|Import|General|Archive File). Anschließend sollte man das Notebook DokuTest.nb starten (rechte Maustaste: Run as Wolfram).

Wenn die Startsequenz erfolgreich ist, kann man im View "Application Tools" das Projekt DokuTest auswählen und den Haken bei "Create HTML" setzen. Klickt man dann auf Build, wird die Dokumentation für das Beispielprojekt erstellt.

Nach erfolgreicher Erstellung der Dokumentation ruft man aus dem Noteboook DokuTest die Funktion PostProcessHTMLDocumentation auf. Ist diese fertig durchgelaufen, findet man als letzte Ausgabe einen Link, der die HTML-Dokumentation im Webbrowser öffnet. Alle Links zu eigenen Symbolen sind nun lokal so angepasst, dass man die Dokumentation durchsuchen kann. Symbole, die zum Funktionsumfang von Wolfram gehören, referenzieren nach wie vor nach reference.wolfram.com.