Yahoo User Interface Blog (YUIBlog)

Carlo Zottmann's Dana Theme for YUI Doc

Ik graag gebruik van YUI Doc voor al mijn documentatie JavaScript nodig heeft. Ik heb ondervonden dat het goed werkt voor het documenteren van 'plain vanilla' JS of jQuery code - het is niet alleen voor YUI -gebaseerde projecten.

Ik was sceptisch in het begin, omdat ik de neiging om meer te schrijven jQuery dan YUI code. Het was een aangename verrassing om te vinden dat YUI Doc eenvoudig te integreren in mijn workflow, en kon nuttige documentatie voor mijn niet-YUI projecten te produceren. Tuurlijk, het heeft een aantal verwachtingen ten aanzien van een project bestand structuur, etc., maar geen van deze verwachtingen zijn showstoppers voor mij. Aan de andere kant is het een licht systeem en ik kan get it up and running in no time.

Het hebben van een hulpmiddel parse mijn broncode automagisch en bouwkwaliteit documentatie voor mij is groot - niet alleen voor het snel opzoeken van functie-aanroepen etc. later, voor mij is een toegevoegde waarde op twee manieren:

Ten eerste, documenteer ik mijn code in beide richtingen voor mijn eigen bestwil - Ik ben waarschijnlijk zal moeten om het opnieuw te bezoeken in een paar maanden en ik zou in staat zijn om het op te rapen snel. Niet over de documentatie betekent zekere verwarring in de toekomst, die niet is een indruk die ik wil mijn klanten geven.

Ten tweede, kan code documentatie een beetje van een abstract begrip voor een klant: Ik kan haar vertellen dat het er, maar de enige manier waarop ik kan "bewijzen" mijn claim wordt door middel van verhitting van mijn redacteur en wijs mijn vinger op het commentaar blokken in mijn code. Die echt zien er niet erg indrukwekkend - in het slechtste geval ze eruit zien als een sorry excuus voor "de juiste" documentatie.

Toch schieten mijn browser en het tonen van de zelfde commentaar geparsed en verwerkt door YUI Doc - schoon, sprankelende, samenhangend - nu is dat professionele code aap daar, mensen.

(Als u dacht "code gedocumenteerd in een wiki is zo goed en minder van een gedoe", neem dan accepteer mijn trieste golf klappen - want is het niet.)

Helaas, ik ben geen fan van de basis YUI Doc huid. Toen ik de hand op een stevig gedocumenteerde stuk van de code om mijn klanten, ik wil dat ze stevig gedocumenteerde code zien, voor mij, is YUI Doc's standaard thema niet schijnen helder genoeg.

Het rondkijken voor vervanging thema's die ik kon geen enkele. Dus een paar weken geleden heb ik besloten om mijn eigen schrijven - Dana . Hier is een voorbeeld screenshot:

Zoals je hierboven kunt zien, heb ik de gegenereerde bekende YUI API docs als een voorbeeld. Hier is de originele YUI documentatie - en hier is het precies dezelfde documentatie sportief het nieuwe Dana thema .

Ik vind de laatste meer een lust voor het oog - ik hoop dat u het ermee eens! Klik op een beetje rond, controleer dan sommige van de klas documentatie voor een meer diepgaande vergelijking, spelen met de filters, voel de luxe en toch goedkope plastic eronder.

Tot nu toe heb ik gekregen veel positieve feedback. Mijn klanten waarderen het schoner uitzien, en ik voel me beter over de meer professionele presentatie van het werk dat ik in mijn projecten, tot aan de gegenereerde markup.

Hoe het werd gebouwd

Ik begon te schrijven Dana door weg te gooien elk beetje van HTML in de standaard YUI Doc sjablonen, te beginnen dan vanaf nul en lagen mijn eigen markup op de top van de kern blokken van YUI Doc Cheetah code. (Cheetah is de Python templating engine wordt gebruikt door YUI Doc. De # blokken vind je in de sjablonen bevatten Python code uitgevoerd door Cheetah.)

Om eerlijk te zijn, uitzoeken wat er gaande is in de sjablonen was niet echt een wandeling in het park - YUI Doc's sjablonen worden niet geannoteerd, en het krijgen van georiënteerd als een nieuwkomer aan het systeem heeft even geduurd. Als ik het gevoel dat ik begreep de structuur en de Cheetah logica had, heb ik ontdaan van de rest van de markup, te vervangen door enkele zeer eenvoudige constructies, en gebouwd op de top van dat. Het duurde een tijdje.

Als je nadenkt over het schrijven van uw eigen thema's, zou ik aanraden hetzij met behulp van Dana's main.tmpl als uitgangspunt, of kijken naar de juiste indeling originele main.tmpl . Velen stierven Bothans om u deze sjabloon.

Ik ben geen ontwerper, ik heb geprobeerd om de look simpel en duidelijk te houden zonder toevoeging van vele toeters en bellen.

Ingebouwde Goodies

Ik heb de vrijheid genomen van de uitvoering van een (naar mijn bescheiden mening) een betere weergave van object-type parameters: als er meerdere parameters worden doorgegeven in als eigenschappen op een enkel object, maar dat object wordt weergegeven als een parameter in de tabellen 'eerste kolommen.

Als voorbeeld, laten we zeggen dat je een methode verwacht een object-type parameter met drie eigenschappen documenteren:

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

Hier is hoe deze methode zou worden weergegeven in de gegenereerde documentatie:

Default theme: method( obj.param1, obj.param2, obj.param3 )
Dana theme: method( obj )

Voor een real-life voorbeeld, zie de docs voor YAHOO.widget.DataTable 's events .

Ik vind dat deze behandeling maakt de uitgang beknopter.

Eisen

Dana vereist een van de latere YUI Doc bouwt , bijvoorbeeld, bouwen 50 werkt prima - maar het zal niet werken met YUI Doc 1.0.0b1.

Installatie / Gebruik

Ik neem aan dat je YUI Doc stond op en draait op dit punt. Gewoon downloaden Dana van GitHub , pak het uit, en vertel yuidoc.py om het te gebruiken via de -t/--template optie.

Slotopmerkingen

Dana is nog steeds een work in progress, er zijn enkele kleine problemen verlaten, bijvoorbeeld bij sommige HTML- code blokken die naar buiten komen te breed. Dit zijn geen deal breakers voor mij, maar uw snelheid kan variëren.

Voor de lezers die, net als ik, duizelig krijgen bij het ​​idee van de Markdown ondersteuning in YUI Doc zoals ik dat doe (hint, hint), check out Mike West YUI Doc vork , die precies dat toevoegt. Terwijl we wachten op een nieuwe originele YUI Doc release, bedoel ik * hoest;.) *

U zult vinden Dana op GitHub . Als je zo geneigd, kunt u de download nieuwste stabiele versie als zip / tgz bestand , ook. Als u problemen ondervindt of fouten, dan kunt u een ticket .

Dana is dual-gelicentieerd onder MIT & GNU GPL v2. Het is getest in Safari 5 (OSX), FF3.6 (OSX), IE8 (WinXP).

Zoek gesprekken: Bloglines | technorati

Delen en uit te breiden: Bookmark met del.icio.us | digg it! | reddit!