Nye funksjoner og et nytt utseende for SassDoc

For noen uker siden presenterte jeg SassDoc på SitePoint mens den fortsatt var i en tidlig utviklingsfase. Siden da har vi gitt ut minst en stor og to mindre versjoner, henholdsvis: 1.0.0, 1.1.0 og 1.2.0. Vi har sendt ganske mange funksjoner ved å gjøre det, så jeg trodde det ville være en god ide å introdusere dem.

Hvis du ikke er kjent med SassDoc, tillat meg å introdusere den. 

Hva er SassDoc?

SassDoc er å Sass hva JSDoc er å JavaScript: et dokumentasjonsverktøy basert på kommentarer i arbeidsfilene dine. Det vanlige scenariet er å skrive kommentarer til dine funksjoner, mixins og variabler som følger dokumentasjonsretningslinjene, kjør SassDoc fra kommandolinjen og boom. Du har selv generert dokumentasjon.

En bedre utsikt

Da jeg først introduserte SassDoc, var den genererte dokumentasjonen bra, antar jeg. I mellomtiden ville jeg virkelig forbedre designet fordi når alt er sagt og gjort, hvis du forteller noen du skal generere vakre dokumenter for dem, kan du bedre få ting riktig og vise dem noe flott!

Så jeg kom opp med en ny mørkbasert design. 

Dette reiste ganske mildret meninger for å være ærlig (selv om jeg hadde mine reservasjoner). Når det er sagt, er skjønnhet i øynene til beholderen, så jeg holdt denne under hatten min og kom opp med et annet design sterkt inspirert av den nye Google Design.

jeg håper du liker det!

Ved siden av denne helt nye skinnende utsikten, la vi til en lett, fuzzy søkemotor basert på Fuse. Dette vil gjøre det lettere for personer med et stort antall dokumenterte elementer å raskt nå den de leter etter, uten å måtte rulle for alltid. På samme linje gjorde vi sidelinjen fast i standardtemaet, slik at du kan holde øye med datastrukturen til enhver tid.

Egendefinerte temaer og maler

I versjon 1.0.0 gjorde vi det mulig for deg å merke visningen ved å gi en bane til en konfigurasjonsfil som inneholder informasjon om prosjektet ditt, for eksempel navn, versjon, beskrivelse, lisens og så videre. Den kule tingen er, hvis du tilfeldigvis har a package.json fil (npm prosjekt) på rotnivå, brukte vi det slik at du ikke må duplisere prosjektets informasjon til SassDoc. Så det er ganske fint.

I 1.2 ønsket vi å presse ting videre. Liker waaay videre. Målet vårt var å gi deg muligheten til å bruke dine egendefinerte temaer og dine tilpassede maler (med din favorittmalmotor). I utgangspunktet ønsket vi å levere dataene til deg slik at du kan gjøre hva du vil med det. Som så:

sassdoc src / mappe destinasjon / mappe --theme my awesome-tema 

Merk: Når du setter inn --tema alternativet til cli-grensesnittet, vil SassDoc søke etter en sassdoc-tema-foo pakke, da ./ foo, og endelig foo.

I mellomtiden ville vi ikke gjøre ting for hardt på siden din, så vi hadde vårt JavaScript-geni Valérian Galliat bygge en temmotor: Themeleon. Dette er et frittstående prosjekt bygget for SassDoc, men helt uavhengig av det. Det er en liten, liten nodemotor som kjører med omtrent 100 linjer med JavaScript.

Du er ikke forpliktet til å bruke Themeleon til å koble temaet ditt til SassDoc, men det gjør jobben enklere fordi det holder alt det tekniske smuss under hetten. Det kommer også med en mixin (slags plugin) for begge malmotorer Swig (themeleon-slurk) og jade (themeleon-jade), for å hindre at du selv trenger å gjøre det som kommer neste gang.

Valérian har skrevet en grundig introduksjon til å bygge og bruke ditt eget tema, så jeg skal bare dekke det grunnleggende her.

Alt temaet må gjøres, er å avsløre en funksjon som implementerer følgende grensesnitt:

/ ** * @param string dest Directory for å gjengi tema i. * @param object ctx Variabler for å passere til temaet. * @return løfte En løfter / A + implementering. * / module.exports = funksjon (dest, ctx) ...; 

Derfra tar Themeleon ansvaret for alt og lar deg skrive temaet ditt uten å plage med "lavt nivå" hensyn, som løftehåndtering, rå fs samtaler, kontroller at målkatalogen finnes, og så videre.

Så handler det om å skape en package.json fil som krever noen avhengigheter (inkludert themeleon og din malmotor, for eksempel themeleon-slurkthemeleon-jade eller hva som helst). I tillegg til en katalog som inneholder en index.js filen som forklart i dokumentene. Da vil denne JavaScript-filen beskrive prosessen for å generere produksjonen.

I vårt standard tema bruker themeleon-slurk, det er så enkelt som:

var themeleon = kreve ('themeleon') (). bruk ('swig'); module.exports = themeleon (__ dirname, funksjon (t) t.copy ('assets'); t.swig ('visninger / dokumentasjon / index.html.swig', 'index.html');); 

Det er det! Hvis du planlegger å bygge ditt eget tema, vil du være glad for å vite at vi har laget en kjele for å hjelpe deg med å komme i gang. Gå videre og les dokumentene, skriv et par linjer, og du vil være god til å gå. Også, gjerne be om hjelp!

Samle dine varer inn i grupper

En funksjon som vi virkelig har glatt oss til i en stund, er evnen til å samle dine varer inn i grupper. Først grupperte vi elementer etter deres type: funksjonmixin og variabel. Når du dokumenterer en enkelt API, var det bra, men da du kjørte SassDoc på større prosjekter, følte det seg litt av.

Dermed kan du nå bruke @gruppe annotasjon etterfulgt av en streng for å definere en gruppe for et element takket være Fabrice Weinbergs gode arbeid. Alle elementer som deler samme gruppe vil bli vist i samme seksjon. Vi holder typen gruppering, så på slutten av dagen virker det slik: gruppe > type > elementer. I mellomtiden alle varer uten en @gruppe annotasjon vil bli samlet i en udefinert gruppe.

For å gi deg mulighet til å nevne gruppene slik du vil, la vi til et aliaseringssystem. For eksempel, hvis du erklærer en gruppe med @grouphjelpere, Du kan legge til et alias til det i konfigurasjonen slik at det vises som "Hjelpere og verktøy" for eksempel. Dette er spesielt nyttig når du vil gi nytt navn til udefinert standardgruppe til noe mer vennlig som "General" eller hva som helst.

Grunt, Gulp og Broccoli Plugins

Hvis du er villig til å innlemme SassDoc som en del av distribusjonsprosessen, vil du gjerne vite at vi allerede har et Grunt-plugin, en Gulp-plugin og en Broccoli-plugin, alle laget av Pascal Duez. Å bruke dem er greit hvis du er kjent med måten hver oppgaveløper fungerer på:

/ * Gulp * / gulp.task ('sassdoc', funksjon () return gulp .src ('bane / til / kilde') .pipe (sassdoc (dest: 'path / to / docs')); ); 
/ * Grunt * / grunt.initConfig (sassdoc: standard: src: 'bane / til / kilde', dest: 'bane / til / docs',); 
/ * Broccoli * / var sassdoc = krever ('brokkoli-sassdoc'); var docs = sassdoc (tre, alternativer); 

Du kan også legge til de samme alternativene som SassDoc regelmessig CLI API, så vær så snill å lese README fra lagerene for å lære mer om hvordan du gjør det!

Se kildekoblinger

Hvis det er en ting jeg virkelig liker i dokumentasjon av noe slag, er det evnen til å gå rett til kildekoden. Det er derfor ingen overraskelse vi har lagt til en se kilde funksjon til SassDoc.

Fordi dette er nært knyttet til visningen, er det mer som et temaelement enn noe fra SassDoc selv. For å si det enkelt, trenger det en basebane fra konfigurasjonsfilen, da koblinger til kilde blir opprettet ved hjelp av basePath +item.file.path, sistnevnte blir beregnet av SassDoc. Av den grunn foreslår vi at du alltid kjører SassDoc fra roten til prosjektet ditt (det hjelper i mange tilfeller).

Hva blir det neste?

Glad du spurte! Vi har fortsatt mange ideer til SassDocs fremtid, og vi er sikker på at du selv har noen interessante meninger. Ikke hold dem for deg selv; dele dem på depotet!

I mellomtiden jobber vi med:

  • en @produksjon annotasjon, ligner på @komme tilbake men for mixins (# 133)
  • gjør det mulig å dokumentere Sass kart på en bedre måte (# 25)
  • gir muligheten til å forhåndsvise hele funksjonen / mixin direkte fra dokumentasjonen (# 124)
  • ... dine ideer? :)