SassDoc, documenta in un lampo il tuo progetto

Scopri come documentare il tuo progetto mentre scrivi il tuo codice SASS con questo semplicissimo strumento!

Lavorare a più mani su uno stesso progetto è una pratica sempre più diffusa, i Jack of the all Trades, master of none sono (in mia opinione) destinati a sparire perché il Web ci porta sempre nuove tecnologie e soluzioni che dobbiamo implementare nel nostro lavoro e se non ci specializziamo in qualcosa sarà ben difficile poterci distinguere dai cugggini della porta accanto.

Ma questa è una cosa che abbiamo detto spesso anche all’interno dei nostri webinar…

Lavorare in team ed essere uno specialista in un campo specifico è sicuramente molto più importante, ma anche in questo contesto talvolta è utile poter collaborare con persone che hanno le stesse conoscenze a livelli diversi.

Nel seguito di questo articolo ti mostrerò meglio che cosa intendo con queste parole, ma prima ancora di farlo voglio presentarti lo strumento che ho trovato nella mia ricerca: SassDoc. Come già successo quando abbiamo parlato di Grunt, faccio riferimento a uno strumento da riga di comando che sarà incredibilmente utile per la tua carriera.

Capisco che spesso questi sono strumenti che tendiamo a evitare, visto l’avvento delle GUI, ma come ti ho confessato più volte ritengo che gli strumenti del futuro (già del nostro presente a essere onesti) sono quelli che possiamo utilizzare senza interfaccia grafica perché sono veloci, affidabili e facili da condividere.

Con SassDoc sarai in grado di generare in automatico una documentazione HTML che ti permetterà di condividere con i tuoi colleghi i vari mixin, funzioni e variabili che hai creato per il progetto che stai sviluppando e potrai anche aggiungere esempi e informazioni aggiuntive che aiuteranno ulteriormente a comprendere e utilizzare il tuo codice.

Anche se da un certo punto di vista può sembrare che tutto venga svolto dal tuo computer, bisogna dire che, come spesso accade, anche noi abbiamo bisogno di imparare qualcosa di nuovo e metterlo in pratica.

Quello che vedrai all’interno di questo articolo tratta principalmente l’implementazione di piccole pratiche che saranno facili da includere nel tuo workflow quindi non ti preoccupare e vieni con me a scoprire questa interessante soluzione!

Cosa è e come si installa SassDoc

Ebbene a questo punto dovrebbe essere chiaro quello che fa SassDoc. Riassumendo: prende in ingresso i tuoi file .scss e genera delle linee guida in HTML e CSS che possono essere comprese da qualsiasi sviluppatore. Se vuoi un esempio di che cosa è in grado di fare SassDoc te ne faccio due, la documentazione di Burbon e quella di Burbon Neat.

Scopri delle librerie utili

Due librerie di mixin molto utili per gli sviluppatori Sass che attraverso i suoi diversi componenti mira a essere il più modulare possibile e semplice da gestire.

Se sei andato a sbirciare le documentazioni che ti ho collegato, avrai notato che la struttura dei due progetti è molto simile e in fin dei conti questo è quello che si ottiene quando utilizziamo uno strumento e non diamo spazio alla nostra creatività.

Allo stesso tempo in questo contesto stiamo creando della documentazione e non un progetto innovativo e dato che la cosa più importante sono le informazioni che condividiamo credo che mettere da parte il nostro orgoglio non dovrebbe far male, tu che ne pensi?

Anzi pensandoci meglio credo proprio che in questi contesti mantenere la stessa struttura e lasciare che lo sviluppatore sia in grado di trovare le informazioni che cerca nel minor tempo possibile sia una caratteristica che ti permetterà di ottenere non pochi consensi.

Ovviamente le due librerie che ti ho presentato fanno parte di un progetto sviluppato per un gran numero di sviluppatori, ma torniamo al nostro punto di interesse: come si fa ad installare e utilizzare SassDoc?

Ebbene, SassDoc non è altro che un pacchetto npm che funziona con Node.js.

È giunto il momento di installare SassDoc nel tuo sistema. Se utilizzi Linux o Mac non dovrai far altro che aprire il tuo terminale e scrivere:

$ npm install sassdoc -g

L’opzione -g permette di installare questo pacchetto in modo globale all’interno del tuo sistema perché altrimenti verrebbe installato all’interno della cartella node_modules/ che viene creata automaticamente all’interno della cartella dove viene eseguito il comando.

Purtroppo non possiedo una macchia Windows ma una volta che avrai installato Node.js e npm seguendo questo tutorial i comandi dovrebbero essere gli stessi, anche se qua sotto ho desiderato aggiungere un piccolo suggerimento per te 😉

Attenzione utenti Windows!

Se sei un utente Windows e ti interessa sviluppare per il web il mio consiglio personale è quello di abbandonare questo sistema operativo, non tanto per interessi personali ma piuttosto perché incontrerai non poche difficoltà a implementare molte delle soluzioni presenti e future all’interno di questi sistemi. Se vuoi una soluzione a costo 0 puoi prendere in considerazione l’installazione di un sistema Linux e puoi prendere qualche spunto da un precedente webinar che abbiamo registrato.

Adesso che hai installato questo strumento sei pronto a lanciarlo con la seguente sintassi:

$ sassdoc - [options]

Questo è il comando che puoi lanciare all’interno della cartella contenente tutti i file .scss e potrai sfruttare le varie [options] per personalizzare il documento HTML che verrà generato.

Questo semplice comando non può fare miracoli da solo, come ti ho detto anche all’inizio di questo articolo, ci sarà bisogno del nostro supporto attraverso l’inserimento di speciali commenti nel nostro codice Sass. Abbiamo scoperto come installare ed eseguire questo interessante strumento, ma come si fa a unirlo al nostro stile di programmazione? Te lo svelo nella prossima sezione!

Come scrivere documentazione grazie a SassDoc

Senza andare ad affrontare da vicino le opzioni che possiamo utilizzare per personalizzare l’output di questo strumento, cosa che puoi approfondire nella pagina dedicata, andiamo invece a capire come poter integrare questo strumento nel tuo lavoro.

Creare la documentazione è tendenzialmente una procedura lunga e noiosa ma è per questo che nascono soluzioni come SassDoc, JSDoc o PHPDoc che sono in grado di automatizzare alcuni di questi aspetti. L’unica cosa che ci viene richiesta di fare è aggiungere i dettagli della documentazione man mano che sviluppiamo il nostro codice.

In questo contesto vorrei riprendere il discorso che ho lasciato a metà durante l’apertura di questo articolo.

Diciamo che siamo un team di tre persone dove tu sei il Sass Master. Il tuo compito è quello di creare le variabili, le funzioni e i mixin da utilizzare all’interno del progetto che sei in grado di estrapolare studiando i mockup che ti vengono consegnati dal grafico. Fatto questo devi passare questi codici e lasciare che sia lo stagista a montare i mockup all’interno di una vera e propria pagina web utilizzando le strutture che tu hai fornito.

Capirai bene da solo che consegnare i tuoi file _variables.scss, _functions.scss e _mixins.scss spesso non è abbastanza e il tuo collega avrà bisogno di un po’ di supporto per comprendere come utilizzare le strutture che gli hai messo a disposizione.

Il fatto è che non sempre è possibile fornire questo tipo di supporto ed ecco che uno strumento come SassDoc diventa veramente utile!

Le logiche che stanno alla base di questo sistema sono incredibilmente semplici perché tutto quello che ci viene chiesto di fare è aggiungere ulteriori commenti al nostro codice in modo che l’applicazione sia in grado di comprendere quali siano le informazioni che stiamo passando.

SassDoc non è uno strumento che si perde troppo in chiacchiere e infatti ci permette subito di lavorare senza dover perdere troppo tempo in lunghe configurazioni. Nel mio progetto di esempio che puoi trovare anche sul nostro repository GitHub, la struttura dei file Sass è la seguente:

style.scss 
_variables.scss
_functions.scss
_mixins.scss

Visto che Sass me lo permette, io preferisco separare il mio codice in modo da essere più ordinato ed utilizzare il file style.scss soltanto per le modifiche generali all’interno del progetto e per includere tutti i parziali che ho creato.

Iniziamo subito analizzando il file _mixins.scss all’interno del quale ho creato un piccolo mixin in grado di creare delle ombre che rispettano lo stile Material Design, che va tanto in voga in questi giorni. Ovviamente non posso aspettarmi che chiunque analizzi il codice sia in grado di utilizzare il mixin, per questo motivo ho iniziato aggiungendo una descrizione:

/// Con questo mixin creo le ombre rispettando i valori del Material Design 

@mixin bshadow( $case ){ 
  ... 
}

Come puoi vedere non è successo niente di strano, sembra un classico commento in linea che al posto di usare due slash ne usa tre. Dal nostro punto di vista può cambiare poco ma per SassDoc questo farà un’enorme differenza.

Ovviamente non basta una descrizione per far capire come utilizzare questo mixin, come già succede in altri linguaggi di programmazione sarebbe utile inserire il tipo di valore che accetta, continuiamo quindi a scrivere:

/// Con questo mixin creo le ombre rispettando i valori del Material Design 
/// @param {int} $case - Permette di definire il tipo di ombra material da utilizzare 
@mixin bshadow( $case ){ ... }

In questo contesto il mixin che ho creato accetta un unico parametro e basta inserire un nuovo commento con tre slash e aggiungere la parola @param per far capire a SassDoc che si trova davanti alla dichiarazione di un parametro per un mixin e che la parola contenuta tra le parentesi graffe {} rappresenta il tipo di valore che viene accettato attraverso $case. Come puoi notare, è anche possibile aggiungere una descrizione che verrà utilizzata all’interno della documentazione.

A questo punto abbiamo fornito già qualche informazione utile, ma molto spesso per aiutare ulteriormente i nostri colleghi la cosa migliore da fare è aggiungere qualche esempio di funzionamento, in SassDoc questo è semplice come utilizzare la parola chiave @example e rispettare qualche regola di spaziatura:

/// Con questo mixin creo le ombre rispettando i valori del Material Design 
/// @param {int} $case - Permette di definire il tipo di ombra material da utilizzare 
/// @example scss - Uso senza parametri 
/// .elemento-con-ombra{ 
///   @include bshadow(); 
/// } 
/// 
/// @example css - Compilato senza parametri 
/// .elemento-con-ombra{ 
///   -moz-box-shadow: rgba(0, 0, 0, 0.12) 0 1px 3px, rgba(0, 0, 0, 0.24) 0 1px 2px; 
///   -webkit-box-shadow: rgba(0, 0, 0, 0.12) 0 1px 3px, rgba(0, 0, 0, 0.24) 0 1px 2px; 
///   box-shadow: rgba(0, 0, 0, 0.12) 0 1px 3px, rgba(0, 0, 0, 0.24) 0 1px 2px; 
/// } 
@mixin bshadow( $case ){ ... }

Ed eccoci pronti con una discreta documentazione per il nostro mixin! Vuoi vedere come risulta questo piccolo esempio? Eccolo rappresentato nell’immagine qua sotto.

Creare questa documentazione è facile quanto scrivere il comando sassdoc sass/ (all’interno del quale specifico la cartella contenente i miei file .scss) che ci permetterà di compilare i file HTML e CSS che compongono la documentazione del mio codice e di salvarli all’interno della cartella sassdoc/ che verrà creata nella root del mio progetto.

Questo risultato si ottiene mantenendo le impostazioni base di questo strumento ma sicuramente non è con questa piccola introduzione che sarai in grado di utilizzarla nella sua completezza. Prima di passare alla sezione conclusiva di questo articolo voglio indicarti la pagina delle altre annotazioni che puoi utilizzare, ovvero tutte le parole che hai visto precedute da @ che hai visto precedentemente.

Le informazioni che puoi aggiungere sono molte ed è possibile costruire delle documentazioni incredibilmente dettagliate come abbiamo già visto per quelle di Bourbon e Bourbon Neat; l’unica cosa che ci viene richiesta di fare è aggiungere qualche commento.

Come pubblicare la tua documentazione

Dato che si sta parlando di file HTML e CSS forse questo titolo può averti un po’ disorientato, in fin dei conti basta un client FTP e un piano hosting in grado di ospitare la tua documentazione; ma molto spesso i progetti che utilizzano SassDoc sono librerie di effetti Sass che vengono rilasciate sotto licenza Open Source e il codice viene ospitato su repository GitHub.

Questo social network per coder ci permette di pubblicare delle pagine pubbiche in grado di presentare il nostro progetto e avere gratuitamente un piano di hosting in grado di collezionare nuovi adepti e utenti interessati.

Creare una Page in GitHub è molto semplice, sopratutto quanto vogliamo farlo per un progetto sul quale lavoriamo. Basta entrare entrare nel repository del progetto e creare una brach di nome gh-pages. Fatto questo non dovrai far altro che pushare la tua documentazione all’interno di questo branch e avrai pronta la pagina per il tuo progetto!

Ti ho parlato di questa possibilità non tanto perché volevo parlare nel dettaglio di GitHub e delle sue funzionalità, piuttosto mi è servito per introdurti un nuovo interessante strumento che ti permette di creare automaticamente la Page del tuo progetto senza neanche dover aprire il repository, dovrai semplicemente lanciare un comando all’interno del tuo terminale.

Il nuovo strumento di cui sto parlando prende il nome di SassDocify e prenderà come riferimento i dati del repository Git presente all’interno del tuo progetto. Per installarlo nel tuo sistema devi semplicemente lanciare npm install sassydocify -g come fatto precedentemente per SassDoc e una volta installato, all’interno della cartella del progetto non devi far altro che lanciare:

$ sassdocify -m Creazione della Page per la documentazione sass/

L’opzione -m ci permette di inserire il messaggio del commit mentre grazie a sass/ identifichiamo la cartella contenente tutti i file .scss utilizzati nel progetto che sassdocify utilizzerà per creare la documentazione e il nuovo branch gh-pages che ci permetterà di pubblicare la documentazione sul progetto.

Terminate le varie operazioni ti verrà suggerito il comando cd .pages && git push -u origin gh-pages dove .pages è la cartella nascosta creata per la tua documentazione e il comando push di Git ti permetterà di caricarla in automatico all’interno del tuo repository. Se vuoi un esempio di quanto siamo stati in grado di creare non devi far altro che consultare la Page creata per il repository di questo progetto dove troverai anche le descrizioni per le funzioni e le variabili utilizzate.

Conclusioni

Con questo articolo spero di averti mostrato un nuovo e interessante strumento che ti permetterà di collaborare meglio con i tuoi colleghi. Personalmente questa è una soluzione che utilizzerò sempre più spesso anche perché, con o senza SassDoc, sono convinto che documentare il proprio codice sia una pratica utile per lavorare a più mani sullo stesso progetto.

Ci sono altri aspetti da prendere in considerazione e molti altri dettagli che dovremmo approfondire come ad esempio la possibilità di creare dei task per Grunt o Gulp che ci consentiranno di automatizzare ulteriormente queste operazioni ma visto che questo articolo ha già superato le 2000 parole vorrei sapere da te se desideri approfondire questi argomenti o meno.

Se hai voglia di farmi sapere che ne pensi non devi far altro che commentare qua sotto.

Altrimenti se ti senti in vena di bontà, puoi condividere questo articolo con i tuoi colleghi per iniziare a lavorare assieme mantenendo uno standard che aiuterà sia il novello sviluppatore che quelli più navigati.