Yahoo! User Interface Blog (YUIBlog)

Carlo Zottmann Dana Theme für YUI Doc

Ich mag zu verwenden YUI Doc für alle meine Bedürfnisse JavaScript Dokumentation. Ich habe festgestellt, dass es gut für die Dokumentation "Plain Vanilla" JS oder jQuery-Code - es ist nicht nur für YUI -basierte Projekte.

Ich war zunächst skeptisch, als ich mehr dazu neigen zu schreiben jQuery als YUI-Code. Es war eine angenehme Überraschung, dass YUI Doc einfach in meinen Workflow integriert und konnten nützliche Informationen für meine nicht-YUI Projekte zu produzieren. Sicher, es hat einige Erwartungen hinsichtlich eines Projekts Dateistruktur etc., aber keiner von diesen Erwartungen sind Showstopper für mich. Auf der anderen Seite ist es ein leichtes System und ich kann es zum Laufen zu bringen in kürzester Zeit.

Mit einem Werkzeug analysiert mein Quellcode und Dokumentation automatisch Bauqualität für mich groß ist - nicht nur für den Blick kurz auf Funktionsaufrufe etc. später, für mich ist es einen Mehrwert in zweierlei Hinsicht:

Erstens Dokument ich meinen Code so oder so um meiner selbst willen - ich bin wohl zu haben, um wieder besuchen sie in ein paar Monaten und ich sollte in der Lage, um ihn abzuholen schnell. Nicht mit Dokumentation bedeutet eine gewisse Verwirrung in der Zukunft, die nicht den Eindruck Ich möchte meine Kunden zu geben.

Zweitens könnten Code Dokumentation ein bisschen ein abstraktes Konzept für einen Kunden sein: Ich kann ihr sagen, sie ist da, aber die einzige Art, wie ich "beweisen" kann mein Anspruch ist durch Brennen mein Editor und Stelle meine Finger auf die Kommentar-Blöcke in meinem Code. Welche wirklich sehen nicht sehr beeindruckend - im schlimmsten Fall sie wie eine Entschuldigung Entschuldigung für "richtige" Dokumentation.

Doch Brand meinen Browser und zeigt die gleichen Kommentare analysiert und durch YUI Doc verarbeitet - sauber, Sekt, kohärenten - jetzt, Berufsordnung monkeying Recht gibt, Menschen.

(Wenn Sie dachte nur "Code Wiki dokumentiert in einem so guten und weniger umständlich", akzeptieren Sie bitte meine traurige Golf klatschen - es ist. Nicht weil)

Leider bin ich kein Fan von der Basis YUI Doc Haut. Als ich mit der Hand über eine solide dokumentiert Stück Code für meine Kunden, ich sie fest dokumentiert Code sehen wollen, für mich geht YUI Doc's Standard-Theme nicht hell genug leuchten.

Sie suchen die für den Ersatz Themen konnte ich nicht finden keine. Also vor ein paar Wochen habe ich beschlossen, eigene schreibe meine - Dana . Hier ein Beispiel-Screenshot:

Wie Sie oben sehen können, habe ich das bekannte YUI API-Dokumentation als ein Beispiel generiert. Hier ist das Original YUI Dokumentation - und hier ist das ganz gleich Dokumentation der neuen sportlichen Dana Thema .

Ich finde diese mehr angenehm für die Augen - ich hoffe, Sie stimmen! Klicken Sie ein bisschen herum, überprüfen Sie einige der Klasse Dokumentationen für eine tiefer gehende Vergleich, spielen mit den Filtern, fühlen sich die luxuriösen und zugleich billiges Plastik darunter.

Bisher habe ich viel positives Feedback bekommen. Meine Kunden schätzen die saubere Look, und ich fühle mich besser über die weitere professionelle Präsentation der Arbeit, die ich in meinen Projekten setzen, bis hin zu den generierten Markup.

Wie sie gebaut wurde

Ich begann Dana durch Wegwerfen jedes bisschen HTML innerhalb des Standard Templates YUI Doc, beginnend bei Null und Schichtung meine eigene Markup auf der Oberseite des Kerns Blöcke von YUI Doc Cheetah -Code. (Cheetah ist das Python-Template-Engine verwendet Doc von YUI. Die # Blöcke, die Sie von Cheetah finden in den Vorlagen enthalten Python-Code ausgeführt.)

Um ehrlich zu sein, herauszufinden, was los ist in den Vorlagen war nicht wirklich ein Spaziergang im Park - YUI Doc's Vorlagen sind nicht kommentiert und immer als ein Neuling in der systemorientierten dauerte einige Zeit. Wenn ich das Gefühl, ich verstand die Struktur und Logik Cheetah hatte, ausgenommen ich den Rest des Markups und ersetzte es durch ein paar wirklich einfache Konstrukte, und baute obendrein. Es dauerte eine Weile.

Wenn Sie schriftlich darüber nachdenken, Ihre eigenen Themen, würde ich empfehlen entweder mit Dana main.tmpl als Ausgangspunkt, oder suchen Sie die richtig formatiert Original main.tmpl . Viele Bothaner starben, um Ihnen diese Vorlage.

Ich bin kein Designer, ich habe versucht zu halten, den Blick einfach und klar, ohne Zugabe von vielen Glocken und Trillerpfeifen.

Built-in Goodies

Ich habe die Freiheit der Einführung eines (IMHO) besser Anzeige von Objekt-Typ-Parameter genommen: wenn mehrere Parameter als Eigenschaften auf ein einzelnes Objekt, nur das Objekt wird als Parameter in den Tabellen 'ersten Spalten angezeigt werden sollen übergeben.

Als ein Beispiel, sagen wir, du bist dokumentieren eine Methode erwartet ein Objekt vom Typ Parameter enthält drei Eigenschaften:

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

Hier ist, wie diese Methode in der generierten Dokumentation angezeigt wäre:

Standard-Design: method( obj.param1, obj.param2, obj.param3 )
Dana Thema: method( obj )

Für ein Beispiel aus der Praxis finden Sie in der Dokumentation für YAHOO.widget.DataTable 's Veranstaltungen .

Ich finde, dass diese Behandlung die Ausgabe übersichtlicher macht.

Bedarf

Dana erfordert eine der später YUI Doc baut , z. B. Build 50 funktioniert gut - aber es wird nicht 1.0.0b1 Arbeit mit YUI Doc.

Installation / Aufruf

Ich nehme an, du hast YUI Doc und läuft an dieser Stelle bekam. Laden Sie sich einfach von Dana GitHub , entpacken Sie es und sagen yuidoc.py die Verwendung es über -t/--template Option.

Schlusswort

Dana ist immer noch ein work in progress, es gibt einige kleinere Probleme hat, zum Beispiel mit einigen HTML- code Blöcke, die herauskommen, zu breit. Diese sind nicht Dealbreakern für mich, aber die Leistung kann variieren.

Für diejenigen Leser, die, wie ich, bekommen Doc schwindlig bei dem Gedanken, Markdown Unterstützung in YUI wie ich (Wink mit dem Zaunpfahl), Besuche Mike West YUI Doc Gabel , dass genau fügt. Während wir warten Freigabe für einen neuen Original YUI Doc, ich meine,. * Hust) *

Sie finden GitHub Dana auf . Wenn Sie so wollen, können Sie zum Download aktuelle stabile Version als zip / tgz-Datei auch. Wenn Fehler auftreten vorhanden, bitte erstellen Sie ein Ticket .

Dana ist dual-lizenziert unter der MIT und GNU GPL v2. Es ist in Safari 5 (OSX), FF3.6 (OSX), IE8 (WinXP) getestet worden.

Finden Gespräche: Bloglines | technorati

Sagen und erweitern: Lesezeichen mit del.icio.us | Digg it! | reddit!