Share
För några veckor sedan introducerade jag SassDoc på SitePoint medan den fortfarande var i en tidig utvecklingsfas. Sedan dess har vi släppt mindre än en stor och två mindre versioner, respektive: 1.0.0, 1.1.0 och 1.2.0. Vi har skickat ett antal funktioner med det, så jag trodde det skulle vara en bra idé att presentera dem.
Om du inte är bekant med SassDoc, låt mig presentera det.
SassDoc är att Sass vad JSDoc är att JavaScript: ett dokumentationsverktyg baserat på kommentarer i dina arbetsfiler. Det vanliga scenariot är att skriva kommentarer för dina funktioner, mixins och variabler enligt dokumentationsriktlinjerna, kör SassDoc från kommandoraden och bommen. Du har själv genererat dokumentation.
När jag först introducerade SassDoc var den genererade dokumentationen okej jag antar. Under tiden ville jag verkligen förbättra designen, eftersom när allt är sagt och gjort, om du berätta för någon du ska skapa vackra dokument för dem, skulle du bättre kunna få saker rätt och visa dem något bra!
Så jag kom fram med en ny mörkbaserad design.
Detta höjde ganska mildrade åsikter för att vara ärlig (även om jag hade mina reservationer). Med detta sagt är skönheten i ögat av den som ser det, så jag höll den här under min hatt och kom med en annan design som var starkt inspirerad av den nya Google Design.
jag hoppas du tycker om det!
Vid sidan av denna helt nya glänsande utsikt lägger vi till en lättviktslös sökmotor baserat på Fuse. Det gör det lättare för personer med ett stort antal dokumenterade objekt att snabbt nå den som de letar efter utan att behöva bläddra för alltid. Samma linjer gjorde vi sidofältet i standardtemat så att du kan hålla koll på datastrukturen hela tiden.
I version 1.0.0 gjorde vi det möjligt för dig att varumärke vyn genom att ge en sökväg till en konfigurationsfil med några uppgifter om ditt projekt, till exempel namn, version, beskrivning, licens och så vidare. Den häftiga saken är, om du råkar ha en package.json fil (npm-projekt) på rotnivå, vi använde det så att du inte behöver duplicera ditt projekts information för SassDoc. Så det är ganska trevligt.
I 1.2 ville vi driva saker längre. Gilla waaay vidare. Vårt mål var att ge dig möjlighet att använda dina anpassade teman och dina anpassade mallar (med din favoritmallmotor). I grund och botten ville vi lämna data till dig så att du kan göra vad du vill med det. Såhär:
sassdoc src / mapp destination / mapp --theme my-awesome-tema
Notera: När du ställer in --tema Alternativet för cli-gränssnittet, SassDoc söker efter a sassdoc-theme-foo paket, då ./ foo, och slutligen foo.
Under tiden ville vi inte göra saker för hårt på din sida så vi hade vårt JavaScript-geni Valérian Galliat byggde en temmotor: Themeleon. Detta är ett fristående projekt byggt för SassDoc men helt oberoende av det. Det är en liten liten Node-temmotor som körs med cirka 100 rader med JavaScript.
Du är inte skyldig att använda Themeleon för att ansluta ditt tema till SassDoc, men det gör jobbet enklare eftersom det håller all teknisk smuts under huven. Det kommer också med en mixin (typ av plugin) för båda mallmotorerna Swig (themeleon-swig) och jade (themeleon-jade), för att förhindra att du ens behöver göra vad som kommer nästa.
Valérian har skrivit en fördjupad introduktion till att bygga och använda ditt eget tema, så jag täcker bara grunderna här.
Allt tema måste göra är att avslöja en funktion som genomför följande gränssnitt:
/ ** * @param string dest Directory för att göra tema i. * @param object ctx Variabler för att passera till temat. * @return promise A Promises / A + implementation. * / module.exports = funktion (dest, ctx) ...;
Därifrån tar Themeleon ansvaret för allt och låter dig skriva ditt tema utan att störa "lågnivå" överväganden, som löften hanterar, råa fs samtal, se till att destinationskatalogen finns och så vidare.
Då handlar det om att skapa en package.json fil som kräver vissa beroenden (inklusive themeleon och din mallmotor, till exempel themeleon-swig, themeleon-jade eller vad som helst). Förutom en katalog som innehåller en index.js filen som förklaras i dokumenten. Då kommer denna JavaScript-fil att beskriva processen för att generera produktionen.
I vårt standardtema med themeleon-swig, det är så enkelt som:
Accentsconagua
var themeleon = require ('themeleon') (). använd ('swig'); module.exports = themeleon (__ dirname, function (t) t.copy ('assets'); t.swig ('visningar / dokumentation / index.html.swig', 'index.html');); Det är allt! Om du planerar att bygga ditt eget tema kommer du vara glad att veta att vi har gjort en panna för att hjälpa dig att komma igång. Gå vidare och läs docs, skriv ett par linjer och du kommer vara bra att gå. Också gärna be om hjälp!
En funktion som vi verkligen ser fram emot för ett tag nu är möjligheten för dig att samla dina föremål i grupper. Först grupperade vi objekt enligt deras typ: fungera, blanda i och variabel. När du dokumenterade ett enda API var det bra, men när du körde SassDoc på större projekt kände det lite av.
Således kan du nu använda @grupp annotation följt av en sträng för att definiera en grupp för ett objekt tack vare Fabrice Weinbergs stora arbete. Alla objekt som delar samma grupp visas i samma avsnitt. Vi behåller typen gruppering, så i slutet av dagen fungerar det så här: grupp > typ > objekt. Under tiden alla objekt utan en @grupp Anteckningen kommer att samlas i en odefinierad grupp.
För att du ska kunna namnge dina grupper så som du vill, lade vi till ett aliasystem. Till exempel, om du förklarar en grupp med @grouphjälpare, Du kan lägga till ett alias i det i konfigurationen så att det visas som "Hjälpare och verktyg" till exempel. Detta är särskilt användbart när du vill byta namn på odefinierad standardgrupp till något mer vänligt som "General" eller vad som helst.
Om du är villig att införliva SassDoc som en del av din installationsprocess, kommer du gärna veta att vi redan har ett Grunt-plugin, ett Gulp-plugin och ett Broccoli-plugin, alla gjorda av Pascal Duez. Att använda dem är okomplicerat om du känner till hur varje uppgift löpare fungerar:
/ * Gulp * / gulp.task ('sassdoc', funktion () return gulp .src ('path / to / source'). Pip (sassdoc (dest: 'path / to / docs') ); / * Grunt * / grunt.initConfig (sassdoc: standard: src: 'sökväg / till / källa', dest: 'path / to / docs',);
/ * Broccoli * / var sassdoc = kräver ("broccoli-sassdoc"); var docs = sassdoc (träd, alternativ); Du kan också lägga till samma alternativ som SassDoc-regelbundet CLI-API, så gärna läsa README från förvaret för att lära dig mer om hur du gör det!
Om det finns en sak som jag verkligen gillar i dokumentation av något slag är det möjligheten att gå direkt till källkoden. Det är därför ingen överraskning vi har lagt till en visa källa funktion till SassDoc.
Eftersom det här är nära kopplat till vyn, är det mer som en temafunktion än något från SassDoc själv. För att uttrycka det enkelt behöver den en basväg från konfigurationsfilen, sedan skapas länkar till källan med basepath +item.file.path, den senare beräknas av SassDoc. Av den anledningen föreslår vi att du alltid kör SassDoc från roten till ditt projekt (det hjälper i många fall).
Glad att du frågade! Vi har fortfarande gott om idéer för SassDocs framtid, och vi är säkra på att du själv har några intressanta åsikter. Förvara dem inte för dig själv; dela dem i förvaret!
Samtidigt arbetar vi med:
@produktion annotation, liknande @lämna tillbaka men för mixins (# 133)