Share
Un paio di settimane fa, ho introdotto SassDoc su SitePoint mentre era ancora in una fase di sviluppo iniziale. Da allora, abbiamo rilasciato non meno di una versione principale e due versioni minori, rispettivamente: 1.0.0, 1.1.0 e 1.2.0. Abbiamo fatto un bel numero di funzioni nel farlo, quindi ho pensato che sarebbe stata una buona idea presentarle.
Se non hai ancora familiarità con SassDoc, permettimi di presentarlo.
SassDoc è per Sass quello che JSDoc è per JavaScript: uno strumento di documentazione basato sui commenti all'interno dei file di lavoro. Il solito scenario è scrivere commenti per le funzioni, mixaggi e variabili seguendo le linee guida della documentazione, eseguire SassDoc dalla riga di comando e boom. Tu stesso hai generato la documentazione.
Quando ho introdotto per la prima volta SassDoc, la documentazione generata era a posto, credo. Nel frattempo, volevo davvero migliorare il design perché, quando tutto è stato detto e fatto, se dici a qualcuno che stai per generare bei documenti per loro, faresti meglio a sistemare le cose e mostrargli qualcosa di grande!
Così ho inventato un nuovo design dark-based.
Ciò ha sollevato opinioni abbastanza mitigate per essere onesti (anche io avevo le mie riserve). Detto questo, la bellezza è negli occhi di chi guarda, quindi ho tenuto questo sotto il mio cappello e ne ho ricavato un altro design fortemente ispirato al nuovo Google Design.
Spero vi piaccia!
Accanto a questa nuovissima vista brillante, abbiamo aggiunto un motore di ricerca fuzzy leggero basato su Fuse. Ciò renderà più semplice per le persone con un numero elevato di elementi documentati di raggiungere rapidamente quello che stanno cercando senza dover scorrere per sempre. Seguendo le stesse linee, abbiamo reso la barra laterale fissa nel tema predefinito in modo da poter tenere d'occhio la struttura dei dati in qualsiasi momento.
Nella versione 1.0.0, abbiamo reso possibile per voi marca la vista fornendo un percorso a un file di configurazione contenente alcune informazioni sul tuo progetto, come il nome, la versione, la descrizione, la licenza e così via. La cosa bella è, se ti capita di avere un package.json file (progetto npm) a livello di root, lo abbiamo usato in modo da non dover duplicare le informazioni del progetto per SassDoc. Quindi è carino.
In 1.2 volevamo spingere oltre. Come mooolto oltre. Il nostro obiettivo era di darti la possibilità di utilizzare i tuoi temi personalizzati e i tuoi modelli personalizzati (con il tuo motore di template preferito). Fondamentalmente, volevamo consegnare i dati a te in modo da poter fare tutto ciò che vuoi con esso. Così:
sassdoc src / cartella destinazione / cartella --theme my-awesome-theme
Nota: Quando imposti il --tema opzione dell'interfaccia cli, SassDoc cercherà a sassdoc-theme-foo pacchetto, quindi ./ foo, e infine foo.
Nel frattempo, non volevamo rendere le cose troppo difficili da parte tua, così il nostro genio JavaScript Valérian Galliat ha creato un motore tematico: Themeleon. Questo è un progetto stand-alone creato per SassDoc ma completamente indipendente da esso. È un piccolo motore a tema Node con circa 100 righe di JavaScript.
Non sei obbligato a usare Themeleon per collegare il tuo tema a SassDoc, anche se rende il lavoro molto più semplice perché mantiene tutto lo sporco tecnico sotto il cofano. Inoltre, viene fornito con un mixin (una specie di plugin) per entrambi i template engine Swig (Themeleon-sorso) e Jade (Themeleon-giada), al fine di evitare di dover anche fare ciò che viene dopo.
Valérian ha scritto un'introduzione approfondita alla costruzione e all'uso del tuo tema, quindi mi limiterò a illustrare le basi qui.
Tutto ciò che il tema deve fare è esporre una funzione che implementa la seguente interfaccia:
/ ** * @param string dest Directory per il rendering del tema. * @param object ctx Variabili da passare al tema. * @return promise Un'implementazione Promises / A +. * / module.exports = function (dest, ctx) ...;
Da lì Themeleon si occupa di tutto e ti permette di scrivere il tuo tema senza preoccuparti di considerazioni "di basso livello", come la gestione delle promesse, raw fs chiama, assicurandosi che la directory di destinazione esista e così via.
Quindi, si tratta di creare un package.json file che richiede alcune dipendenze (incluso Themeleon e il tuo motore di template, per esempio Themeleon-sorso, Themeleon-giada o qualsiasi altra cosa). Così come una directory contenente un index.js file come spiegato nei documenti. Quindi questo file JavaScript descriverà il processo per generare l'output.
Nel nostro tema predefinito usando Themeleon-sorso, è semplice come:
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');); Questo è tutto! Se hai in programma di creare il tuo tema, sarai felice di sapere che abbiamo creato una struttura per aiutarti a iniziare. Vai avanti e leggi i documenti, scrivi un paio di righe e sarai a posto. Inoltre, non esitare a chiedere aiuto!
Una funzione che abbiamo atteso con impazienza da un po 'di tempo è la possibilità di raccogliere i tuoi articoli in gruppi. Inizialmente, abbiamo raggruppato gli articoli in base al loro tipo: funzione, mixin e variabile. Quando si documentava una singola API, andava bene, ma quando si eseguiva SassDoc su progetti più grandi si sentiva un po 'fuori.
Quindi, ora puoi usare il @gruppo annotazione seguita da una stringa per definire un gruppo per un oggetto grazie al grande lavoro di Fabrice Weinberg. Tutti gli articoli che condividono lo stesso gruppo verranno visualizzati nella stessa sezione. Manteniamo il raggruppamento dei tipi, quindi alla fine della giornata funziona così: gruppo > genere > elementi. Nel frattempo tutti gli articoli senza a @gruppo l'annotazione sarà raccolta in un non definito gruppo.
Per consentirti di assegnare un nome ai tuoi gruppi nel modo desiderato, abbiamo aggiunto un sistema di aliasing. Ad esempio, se dichiari un gruppo con @gruppi di aiuto, è possibile aggiungere un alias ad esso nella configurazione in modo che venga visualizzato come "Helpers and Tools", ad esempio. Questo è particolarmente utile quando si desidera rinominare il non definito gruppo predefinito in qualcosa di più amichevole come "Generale" o qualsiasi altra cosa.
Se desideri integrare SassDoc come parte del processo di distribuzione, sarai felice di sapere che abbiamo già un plug-in Grunt, un plug-in Gulp e un plug-in Broccoli, tutti realizzati da Pascal Duez. Usarli è semplice se si ha familiarità con il funzionamento di ogni task runner:
/ * Gulp * / gulp.task ('sassdoc', function () return gulp .src ('path / to / source') .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 (albero, opzioni); Puoi anche aggiungere le stesse opzioni dell'API CLI regolare di SassDoc, quindi sentiti libero di leggere il README dai repository per saperne di più su come farlo!
Se c'è una cosa che mi piace molto nella documentazione di qualsiasi tipo è la possibilità di andare direttamente al codice sorgente. Non è quindi una sorpresa che abbiamo aggiunto un vedi la fonte funzione per SassDoc.
Poiché questo è strettamente legato alla vista, è più simile a una caratteristica del tema che a qualcosa della stessa SassDoc. Per dirla semplicemente, ha bisogno di un percorso di base dal file di configurazione, quindi i collegamenti al sorgente vengono creati usando basePath +item.file.path, quest'ultimo viene calcolato da SassDoc. Per questo motivo, ti suggeriamo di eseguire sempre SassDoc dalla radice del tuo progetto (in molti casi aiuta).
Sono contento che l'abbiate chiesto! Abbiamo ancora un bel po 'di idee per il futuro di SassDoc e siamo certi di avere delle opinioni interessanti da soli. Non tenerli per te; condividili sul repository!
Nel frattempo, stiamo lavorando su:
@produzione annotazione, simile a @ritorno ma per mixins (# 133)