Share
Een paar weken geleden introduceerde ik SassDoc op SitePoint terwijl het zich nog in een vroege ontwikkelingsfase bevond. Sindsdien hebben we niet minder dan één major en twee minorversies uitgebracht, respectievelijk: 1.0.0, 1.1.0 en 1.2.0. We hebben een groot aantal functies meegeleverd, dus ik dacht dat het een goed idee zou zijn om ze te introduceren.
Als je nog niet bekend bent met SassDoc, sta me toe het te introduceren.
SassDoc is voor Sass wat JSDoc voor JavaScript is: een documentatietool op basis van opmerkingen in uw werkbestanden. Het gebruikelijke scenario is om opmerkingen te schrijven voor uw functies, mixins en variabelen volgens de documentatie richtlijnen, SassDoc uitvoeren vanaf de opdrachtregel en boem. Je hebt zelf documentatie gegenereerd.
Toen ik SassDoc voor het eerst introduceerde, was de gegenereerde documentatie ok denk ik. Ondertussen wilde ik het ontwerp echt verbeteren omdat, als alles is gezegd en gedaan, als je iemand vertelt dat je mooie documenten voor hem gaat genereren, je de dingen beter goed kunt maken en ze iets geweldigs laten zien!
Dus bedacht ik een nieuw, op dark gebaseerd ontwerp.
Dit leverde nogal gematigde meningen op om eerlijk te zijn (zelfs ik had mijn bedenkingen). Dat gezegd hebbende, schoonheid zit in het oog van de toeschouwer, dus hield ik deze onder mijn hoed en kwam met een ander ontwerp dat sterk geïnspireerd was door het nieuwe Google Design.
ik hoop dat je het leuk vind!
Naast deze gloednieuwe glimmende weergave hebben we een lichtgewicht fuzzy-zoekmachine toegevoegd op basis van Fuse. Dit maakt het gemakkelijker voor mensen met een groot aantal gedocumenteerde items om snel het gezochte te bereiken zonder voor eeuwig te hoeven scrollen. In dezelfde lijn hebben we de zijbalk gerepareerd in het standaardthema, zodat u de gegevensstructuur altijd in de gaten kunt houden.
In versie 1.0.0 hebben we het voor u mogelijk gemaakt om dit te doen merk de weergave door een pad naar een configuratiebestand te bieden met enkele informatie over uw project, zoals de naam, de versie, de beschrijving, de licentie, enzovoort. Het leuke is, als je toevallig een hebt package.json bestand (npm-project) op hoofdniveau, we hebben het gebruikt, zodat u de gegevens van uw project voor SassDoc niet hoeft te dupliceren. Dus dat is best aardig.
In 1.2 wilden we dingen verder duwen. Zoals verder Waaay. Ons doel was om u de mogelijkheid te geven uw aangepaste thema's en uw aangepaste sjablonen te gebruiken (met uw favoriete sjabloonengine). Kort gezegd wilden we de gegevens aan u overhandigen zodat u ermee kunt doen wat u maar wilt. Zoals zo:
sassdoc src / map bestemming / map - thema my-awesome-thema
Notitie: Wanneer u de --thema optie van de cli-interface zoekt SassDoc naar een sassdoc-theme-foo pakket dan ./ foo, en tenslotte foo.
Ondertussen wilden we het je niet te moeilijk maken, dus we hadden onze JavaScript-genie Valérian Galliat een themamotor laten bouwen: Themeleon. Dit is een op zichzelf staand project gebouwd voor SassDoc, maar volledig onafhankelijk van het. Het is een piepkleine Node-thema-engine met ongeveer 100 regels JavaScript.
Je bent niet verplicht om Themeleon te gebruiken om je thema in SassDoc te pluggen, hoewel het het werk veel gemakkelijker maakt omdat het alle technische vervuiling onder de motorkap houdt. Ook wordt het geleverd met een mixin (soort van een plug-in) voor beide template-engines Swig (themeleon-swig) en Jade (themeleon-jade), om te voorkomen dat u zelfs hoeft te doen wat erna komt.
Valérian heeft een grondige inleiding geschreven over het bouwen en gebruiken van je eigen thema, dus ik zal hier alleen de basis behandelen.
Het enige wat het thema hoeft te doen is een functie blootstellen die de volgende interface implementeert:
/ ** * @param string dest Directory om het thema weer te geven. * @param object ctx Variabelen om door te geven aan het thema. * @return beloven Een implementatie van Promises / A +. * / module.exports = functie (dest, ctx) ...;
Vanaf daar neemt Themeleon de leiding over alles en stelt het je in staat om je thema te schrijven zonder zich te bekommeren om 'low-level'-overwegingen, zoals het omgaan met beloften, fs oproepen, zorg ervoor dat de doelmap bestaat, enzovoort.
Vervolgens draait alles om het creëren van een package.json bestand dat afhankelijkheden vereist (inclusief themeleon en uw sjabloonengine, bijvoorbeeld themeleon-swig, themeleon-jade of wat dan ook). Evenals een map met een index.js bestand zoals uitgelegd in de documenten. Vervolgens beschrijft dit JavaScript-bestand het proces voor het genereren van de uitvoer.
In ons standaardthema gebruiken themeleon-swig, het is zo simpel als:
Accentsconagua
var themeleon = require ('themeleon') (). use ('swig'); module.exports = themeleon (__ dirname, function (t) t.copy ('assets'); t.swig ('views / documentation / index.html.swig', 'index.html');); Dat is het! Als u van plan bent om uw eigen thema te bouwen, zult u blij zijn te weten dat we een standaard plaatje hebben gemaakt om u op weg te helpen. Ga je gang en lees de documenten, schrijf een paar regels en je bent klaar om te gaan. Voel je ook vrij om hulp te vragen!
Een eigenschap waar we nu al een tijdje naar uitkijken, is de mogelijkheid om je items in groepen te verzamelen. In eerste instantie hebben we items gegroepeerd op basis van hun type: functie, mixin en veranderlijk. Bij het documenteren van een enkele API was het prima, maar bij het uitvoeren van SassDoc op grotere projecten voelde het een beetje weg.
U kunt nu dus de @groep annotatie gevolgd door een tekenreeks om een groep voor een item te definiëren dankzij het geweldige werk van Fabrice Weinberg. Alle items die dezelfde groep delen, worden in dezelfde sectie weergegeven. We behouden de typegroep, dus aan het einde van de dag werkt het als volgt: groep > type > items. Ondertussen alle items zonder een @groep annotatie zal worden verzameld in een onbepaald groep.
Om u toe te staan uw groepen een naam te geven zoals u dat wilt, hebben we een aliasingsysteem toegevoegd. Bijvoorbeeld als u een groep aangaf met @group helpers, je kunt er een alias aan toevoegen in de configuratie, zodat het bijvoorbeeld wordt weergegeven als "helpers en tools". Dit is vooral handig als u de naam wilt wijzigen onbepaald standaardgroep in iets vriendelijkers zoals "Algemeen" of wat dan ook.
Als u bereid bent om SassDoc op te nemen als onderdeel van uw implementatieproces, zult u blij zijn te weten dat we al een Grunt-plug-in, een Gulp-plug-in en een Broccoli-plug-in hebben, allemaal gemaakt door Pascal Duez. Het gebruik ervan is eenvoudig als u bekend bent met de manier waarop elke taak runner werkt:
/ * Gulp * / gulp.task ('sassdoc', function () return gulp. Src ('pad / naar / bron') .pipe (sassdoc (dest: 'path / to / docs')) ); / * Grunt * / grunt.initConfig (sassdoc: default: src: 'path / to / source', dest: 'path / to / docs',);
/ * Broccoli * / var sassdoc = require ('broccoli-sassdoc'); var docs = sassdoc (tree, options); U kunt ook dezelfde opties toevoegen als de standaard CLI API van SassDoc, dus lees de README van de repositories voor meer informatie over hoe u dit kunt doen!
Als er iets is dat ik echt leuk vind in documentatie van welke aard dan ook, dan is het de mogelijkheid om rechtstreeks naar de broncode te gaan. Het is daarom geen verrassing dat we er een hebben toegevoegd bekijk de bron functie van SassDoc.
Omdat dit nauw verbonden is met het uitzicht, is het meer een themafunctie dan iets van SassDoc zelf. Om het simpel te zeggen, het heeft een basispad nodig van het configuratiebestand, dan worden links naar bron gemaakt met behulp van basePath +item.file.path, de laatste wordt berekend door SassDoc. Daarom raden we aan dat u SassDoc altijd vanuit de hoofdmap van uw project uitvoert (in veel gevallen helpt dit).
Blij dat je vroeg! We hebben nog steeds veel ideeën over de toekomst van SassDoc en we zijn er zeker van dat je zelf een aantal interessante meningen hebt. Bewaar ze niet voor jezelf; deel ze op de repository!
Ondertussen werken we aan:
@output annotatie, vergelijkbaar met @return maar voor mixins (# 133)