Vom Code zur Dokumentation - Teil 02.- Die Sandcastle Help File Builder GUI

Was bisher geschah

1. Prerequisits und Vorbereitungen
2. Die Sandcastle Help File Builder GUI
3. Wie dokumentiere ich richtig - Referenzdokumentation
4. Wie dokumentiere ich richtig - Benutzerdokumentation
5. ...

Was erwartet uns?

Im ersten Teil unserer Serie habe ich gezeigt wie in ein paar kurzen Schritten mit geringem Zeitaufwand eine vorzeigbare Dokumentation erstellt werden kann. In diesem Teil der Serie führe ich in die Funktionalität des Tools Sandcastle Help File Builder (SHBF) ein, wie sich dieses Tool für ein neues Projekt einrichten lässt und welche dieser Funktionen besonders hilfreich sind.

Unser Ziel

Wir wollen mit Sandcastle eine Dokumentation erstellen, die am Ende aussieht wie die Dokumentation der MSDN. Dazu lernen wir im ersten Schritt den SHFB kennen und ich zeige euch was für Möglichkeiten er bietet uns unserem Ziel etwas näher zu bringen. In einem späteren Artikel erstellen wir dann anhand des gelernten dann unsere Beispieldokumentation.

Inhalt

Die SHFB GUI:

1. Was ist das
2. Wie bediene ich sie
3. Wo befinden sich wichtige Funktionen
   1. Assemlbies to Document
   2. Additional and Conceptual Content
   3. Build-Components
   4. Build-Plugins
   5. API-Filter
4. Wie beeinflusse ich den Output

Los gehts!

Was ist das?

SHFB ist ein Frontend, eine GUI für Sandcastle. Wer NDoc kannte, wird auch mit SHFB keine Probleme haben. Es lassen sich auch Projekte aus NDoc importieren. Dieses kleine Programm läuft unabhängig von Visual Studio und kann also auch ohne Probleme mit der Express Version, oder anderen IDEs benutzt werden, die das Generieren der XML-Kommentare unterstützen. Zur Erstellung der Dokumentation mit Sandcastle eignet sich der SHFB also perfekt um schnell ein Ergebniss zu sehen, wie bereits in Teil 01. bewiesen wurde. Mit dem Frontend lassen sich alle wichtigen Parameter von Sandcastle steuern, sowie zusätzliche Komponenten und Plugins einfügen und verwalten, um die ausgegebene Hilfedatei anzureichern (z.B. eingefärbte Code-Blöcke mit Copy-Link). Eine weitere, sehr hilfreiche Funktion ist das Erstellen von zusätzlichen Hilfedokumenten mit der Microsoft Application Markup Language (MAML) als sogenannter Conceptual Content.

Wie bediene ich sie?

Eine komplizierte Arbeitsumgebung sucht man hier vergebens. Dieses kleine, hilfreiche Tool lässt sich sehr intuitiv bedienen. Nach dem Starten sticht einem sofort das "Assemblies to Document" Edit-Kontroll, sowie das Property-Grid (siehe Abbildung 1. ) ins Auge. Über den Button "Add" können zum Projekt Assemblys inklusive ihrer XML-Kommentar-Dateien hinzugefügt werden. Hier werden nur die Assemblys hinterlegt, die auch wirklich dokumentiert werden. Abhängigkeiten werden an einer anderer Stelle konfiguriert. Alle anderen wichtigen Merkmale, Optionen und zusätzliche Dokumente werden über das Eigenschaften-Fenster eingestellt. Es bietet neben den einfachen bekannten true/false Triggern und Comboboxen erweiterte, komplexere Konfigurationsdialoge, z.B. für die Plugins und einen sehr Umfangreichen Editor für zusätzliche Hilfedokumente.

Wo befinden sich wichtige Funktionen?

Assemblies to Document

Die wichtigste Funktion zum dokumentieren von Quellcode habe ich bereits erwähnt. Über "Add" werden alle zu dokumentierenden Assemblies hinterlegt, die später in der Hilfe erscheinen sollen. Wer nicht alles dokumentieren will findet mit dem API-Filter (siehe weiter unten) die Möglichkeit Teile des zu dokumentieren Sourcecodes auszuklammern. Gibt es abhängige Dateien, die von SHFB benötigt werden um die Reflektionsdateien für die XML-Kommentare zu erstellen, können sie im Eigenschaftsfenster unter "Build/Dependencies" hinzugefügt werden. Da sich im Sourcecode keine Namespaces dokumentieren lassen, können wir über den Button Namespaces dies für die jeweiligen tun. Es öffnet sich ein Dialog zum Filtern der Namespaces (siehe Abblidung 2.)

Additional and Conceptual Content

Die wohl umfangreichste und meiner Meinung nach auch wichtigste Funktion, wenn es darum geht, das Konzept, die Gedanken und Ideen zu dokumentieren ist der Bereich "Additional and Conceptual Content". Mit der Anfang Juni erschienenen und aktuellen Version 1.7.0.0 des SHFB wurde das alte HTML basierte Format der *.topics abgelöst. Das Rendering mit den Sandcastle Stylesheets wird unterstützt und der Anwender kann mit HTML und einigen plugineigenen Tags die Erzeugung beeinflussen. Die neue strukturierte Formatierung löst die Erstellung nun komplett ab - Topics im alten Format sind obsolet. Es wird hier nur noch Bugfixes geben. Das Format der Zukunft heißt MAML. Es ist Xml basiert und bietet ein Schema zum Erstellen an. Der Editor für Conceptual Help (siehe Abbildung 3.) besteht aus  sechs grundlegenden Bereichen.

1. Editorauswahl
2. Content-Auflistung
3. Content-Eigenschaften
4. Content-Fenster
5. Preview-Fenster
6. Code-References-Fenster

Editorauswahl

Sie ist nochmals in vier Unterbereiche aufgeteilt:

• Codesnippets: Diese Snippets sollen bitte nicht mit denen aus dem Visual Studio verwechselt werden. Mit ihnen können Code-Beispiele erstellt werden, auf die dann referenziert werden kann, ohne jedes mal das gleiche Beispiel neu zu erstellen.
• Images: Grafiken, die in die Hilfe eingebunden werden, müssen in diesem Editor erfasst werden. Im Hintegrund wird eine Xml-Datei gefüllt. Per Drag&Drop aus dem Images-Editor auf das Content-Fenster wird der Medieninhalt bereit gestellt. Wichtig: Bilder werden in den Ordner .\Media kopiert und müssen deshalb eindeutig sein
• Token: Wie bei einem ASP.NET User-Control kann hier Funktionalität gesammelt und in den Topics als eigener Tag eingebunden werden, der dann zur Kompilierzeit ersetzt wird. Das Token kann man sich als eine Art Widget vorstellen.
• Topics: Der wichtigste und größte Bereich mit dem der eigentliche Inhalt erstellt wird. Über "Content/Add Sibling Topic/Standart Templates" oder "Content/Add Child Topic/Standart Templates" werden der Hilfe neue Themen hinzugefügt. Das bearbeiten erfolgt im Moment leider nur Textbasiert und bietet nur eine Pseudo WYSIWYG Funktion. Nach drücken auf F5 wird der Inhalt gerendert im Preview-Fenster angezeigt - leider nicht editierbar. Es reicht aber um intuitiv und schnell zu einem Ergebnis zu kommen. Alternativ kann direkt im Visual Studio mit dem XML-Editor gearbeitet werden. Das erfordert aber mehr Aufwand, da die Medieninhaltsliste selbst gepflegt werden muss und keine Tokens, sowie Codesnippets zur Verfügung stehen.

Content-Auflistung

Abhängig vom ausgewählten Editor findet sich hier eine strukturierte Sitemap des jeweilgen Inhaltes. Bei Topcis ist es die TOC mit einem Treeview des Inhaltes (siehe Abbildung 3. Nr. 2). Bei den anderen Editoren ist es jeweils eine Auflistung der vorhandenen Instanzen. Per Drag & Drop werden die Einträge aus diesen Listen in den Editor gezogen werden um den Inhalt in dem Topic zu platzieren. Bei Bildern z.B. öffnet sich ein weiteres Kontextmenü um die Art und Weise, wie verlinkt wird zu auszuwählen.

Content-Eigenschaften

Diese Fenster ist bei Benutzung selbsterklärend. Bei Tokens wir in dem Eigenschaftsfenster der Inhalt unter TolenValue eingegeben. Das Content-Fenster bleibt in diesem Fall unbenutzt. Ist der Topic-Editor selektiert können zusätzliche Schlüsselworte im Bereich TopciMetadate hinterlegt werden, um das Thema später wieder im Index wieder zu finden. Wer näheres zu dem Thema Keywords aus diesem Bereich wissen will oder muss sollte sich mit Help 2 Data Island beschäftigen. Mit den einzelnen Indezes werden die verschiedene Kategorien verwalten, z.B. die kontextsensitive Hilfe per F1. Wer also seine Hilfedatei in seine Applikation einbinden und kontextabhängig anzeigen will, sollte sich diesem Thema näher widmen.

Content-Fenster

Ähnlich einem HTML-Source Editor kann hier der Inhalt bearbeitet und erweitert werden. Ist ein Topic geöffnet und in der Editorauswahl ein anderer Editor eingestellt  z.B. Images kann aus der Content-Auflistung das Bild in den Editor gezogen werden um es einzufügen. Der Editor ist im Moment leider nicht WYSIWYG, bietet daher nur eine Ansicht des Markupcodes...

Preview-Fenster

Lediglich eine Voransicht (F5) lässt sich generieren, die sich bei der Erstellung aber schon als sehr hilfreich erweist. Das navigieren innerhalb der Topics und Links (soweit vorhanden) ist möglich und das "Look and Feel" der fertigen Dokumentation kann überprüft werden. Ein weiteres Plus: Rechtschreibfehler werden in dieser Ansicht leichter aufgedeckt.

Code-References-Fenster

Was wäre die Dokumentation, wenn schlussendlich nicht auch für den Entwickler auf den Sourcecode verwiesen werden könnte. Die Suche nach vorhandenen Referenzen aus den zu dokumentieren Assemblys geht mit dieser Toolbox ganz leicht von der Hand. Nach betätigen von F3 sucht SHFB die möglichen Referenzen zusammen. In die Editbox "Find" kann nun die gewünscht Codereferenz eingeben werden. Mit "Enter" wird gesucht. Aus der gefundenen Auswahl kann nun wieder - wie schon gewohnt - per Drag & Drop die entsprechende Referenz im Conent-Fenster hinterlegt werden.

Build - ComponenteConfigurations

Es gibt eine Funktion die nicht in Sandcastle integriert ist. Hier kann der geneigte User sein Glück versuchen um Sandcastle zu erweitern. Ein entsprechendes HowTo ist in der Hilfe zu finden. "Custom Components" sollten dann verwendet werden, wenn der gerenderte Output von Sandcastle, also das fertig generierte HTML-Markup in der Hilfedatei selbst erstellt wird. Sandcastle wird in diesem Fall um neue Funktionalität erweitert. Wo findet die Konfiguration statt? Genau an dieser Stelle.

Build - PlugInConfigurations

Mit den PlugIns kann der Buildprozess direkt beinflusst werden. Hier muss ein entsprechendes Interface implementiert und in einer Assembly bereit gestellt werden. Das Plugin bekommt einen Build-Prozess-Context übergeben, den es zum manipulieren und erweitern benutzen kann. In der Hilfe befindet sich ein entsprechendes Skeleton für ein Plugin. Der SHFB selbst stellt auch schon Erweiterungen über diesen Mechanismus bereit. Denkbar wäre z.B. ein Xml-Tag video der eine Komponente für die einen Flash- oder WMV-Player bereitstellt.

API-Filter

Dieser Filter ermöglicht das Manipulieren des zu erstellenden Inhaltes. Wer mag sein Steak würzig? Will ich z.B. eine bestimmten Klasse nicht in meiner Hilfe dokumentieren, wird diese hier einfach deaktiviert. Sogar ganze Namespaces sind kein Problem. Hier können nach belieben die Bestandteile der Dokumentation manipuliert werden. Salz und Pfeffer, aber bitte kein Oregano!

Fazit

Alles kann, nichts muss. Es gibt viele Möglichkeiten die Ausgabe zu beeinflussen. Sogar eigene Funktionalität lässt sich erstellen. Mit dem "Additional Content" bietet der SHFB darüber hinaus eine sehr gute Möglichkeit Konzepte zu erfassen und die trockene Referenzdokumentation um lebendigen und verständlichen Inhalt zu erweitern.

Aussichten

Der nächste Artikel wird sich mit den XML-Kommentaren im Code selbst befassen. Wir werden hier nun ein erstes Beispiel anfangen und zeigen, wie wir mit vorhanden Tags auch auf "Additional Content" verweisen können. Der darauf folgende Artikel - Teil 04. - wird das ganze dann aus der anderen Perspektive beleuchten und dadurch ein einheitliches Dokumentationsgebilde entstehen lassen.