Share
Cu câteva săptămâni în urmă, am introdus SassDoc la SitePoint în timp ce era încă într-o fază de dezvoltare timpurie. De atunci, am lansat nu mai puțin de o versiune majoră și două versiuni minore, respectiv: 1.0.0, 1.1.0 și 1.2.0. Am trimis o mulțime de caracteristici în acest sens, așa că am crezut că ar fi o idee bună să le prezentăm.
Dacă nu sunteți încă familiarizat cu SassDoc, permiteți-mi să o introduc.
SassDoc este să Sass ceea ce JSDoc este pentru JavaScript: un instrument de documentare bazat pe comentarii în fișierele de lucru. Scenariul obișnuit este de a scrie comentarii pentru funcțiile, mixurile și variabilele care respectă instrucțiunile de documentare, executați SassDoc din linia de comandă și boom-ul. Dvs. ați generat documentația.
Când am introdus pentru prima oară SassDoc, documentația generată a fost bine, cred. Între timp, am vrut cu adevărat să îmbunătățesc designul, pentru că, atunci când totul este spus și făcut, dacă îi spui cuiva că vei genera docuri frumoase pentru ei, ar fi mai bine să faci lucrurile în regulă și să le arăți ceva grozav!
Așa că am venit cu un nou design întunecat.
Acest lucru a ridicat opinii destul de atenuate pentru a fi cinstit (chiar am avut rezervele mele). Acestea fiind spuse, frumusețea este în ochii privitorului, așa că am păstrat-o sub pălăria mea și am venit cu un alt design puternic inspirat de noul design Google.
sper că îți place!
Alături de această nouă viziune strălucitoare, am adăugat un motor de căutare fuzzy ușor, bazat pe Fuse. Acest lucru va face mai usor pentru persoanele cu un numar mare de documente documentate sa ajunga rapid la cel pe care il cauta fara a trebui sa parcurgeti pentru totdeauna. Pe aceleași linii, am făcut bara laterală fixată în tema prestabilită, astfel încât să puteți păstra un ochi pe structura de date în orice moment.
În versiunea 1.0.0, am făcut posibil acest lucru marca vizualizarea oferind o cale către un fișier de configurare care conține câteva informații despre proiect, cum ar fi numele, versiunea, descrierea, licența și așa mai departe. Lucrul grozav este, dacă se întâmplă să ai a package.json fișier (proiect npm) la nivelul rădăcină, am folosit-o astfel încât să nu trebuiască să duplicați informațiile despre proiectul dvs. pentru SassDoc. Deci, e drăguț.
În 1.2 am vrut să împingem lucrurile mai departe. Ca și mai mult. Scopul nostru a fost să vă oferim posibilitatea de a utiliza temele personalizate și șabloanele personalizate (cu ajutorul motorului de șablon preferat). Practic, am vrut să vă dăm datele, astfel încât să puteți face tot ceea ce doriți. Ca astfel:
sassdoc src / dosarul destinație / folder - tema tema mea minunată
Notă: Când setați --temă opțiunea de interfață cli, SassDoc va căuta o sassdoc-tema-foo pachet, atunci ./ foo, și, în sfârșit foo.
Între timp, nu am vrut să facem lucrurile prea greu de partea ta, așa că am avut geniul JavaScript Valérian Galliat construi un motor tematic: Themeleon. Acesta este un proiect stand-alone construit pentru SassDoc, dar complet independent de acesta. Este un motor minuscul tematic Nod care rulează cu aproximativ 100 de linii de JavaScript.
Nu ești obligat să folosești Themeleon pentru a conecta tema la SassDoc, deși face mai ușor locul de muncă, deoarece păstrează toată murdăria tehnică sub capota. De asemenea, vine cu un mixin (un fel de plugin) pentru ambele motoare template Swig (themeleon-înghițitură) și Jade (themeleon-jad), pentru a vă împiedica chiar să trebuiască să faceți ce urmează.
Valérian a scris o introducere aprofundată în construirea și utilizarea propriei tematici, așa că voi acoperi doar elementele de bază aici.
Toată tema trebuie să facă este să expuneți o funcție care să implementeze următoarea interfață:
/ ** * @param string dest Directory pentru a reda tema în. * @param object ctx Variabilele care trec la temă. * @return promisiune O promisiune / implementare A +. * / modul.exports = funcție (dest, ctx) ...;
De acolo, Themeleon se ocupă de tot și vă permite să vă scrieți tema fără a vă deranja cu considerații "la un nivel scăzut", cum ar fi manipularea promisiunilor, fs apeluri, asigurându-vă că există directorul de destinație și așa mai departe.
Apoi, este vorba despre crearea unui package.json fișier care necesită unele dependențe (inclusiv themeleon și de exemplu motorul șablonului themeleon-înghițitură, themeleon-jad sau orice altceva). Pe lângă un director care conține un index.js fișier așa cum este explicat în doc. Apoi acest fișier JavaScript va descrie procesul de generare a ieșirii.
În tema noastră implicită themeleon-înghițitură, este la fel de simplu ca:
Accentsconagua
var themeleon = cer ('themeleon') () utilizarea ('swig'); modul.exports = themeleon (__ dirname, funcția (t) t.copy ('assets'); t.swig ('views / document / index.html.swig', 'index.html'); Asta e! Dacă aveți de gând să vă construiți propria temă, veți fi încântați să știți că am făcut o plută pentru a vă ajuta să începeți. Du-te și citiți documentele, scrieți câteva linii și veți fi bine să mergeți. De asemenea, nu ezitați să cereți ajutor!
O caracteristică pe care am așteptat-o într-adevăr pentru un timp, acum este capacitatea de a vă aduna articolele în grupuri. La început, am grupat articolele după tipul lor: funcţie, mixin și variabil. Când documentați un singur API, a fost bine, dar atunci când rulați SassDoc pe proiecte mai mari, sa simțit puțin.
Astfel, puteți utiliza acum @grup adnotare urmată de un șir de caractere pentru a defini un grup pentru un articol datorită muncii minunate a lui Fabrice Weinberg. Toate elementele care au același grup vor fi afișate în aceeași secțiune. Păstrăm gruparea de tip, deci la sfârșitul zilei funcționează astfel: grup > tip > articole. Între timp toate elementele fără a @grup adnotarea va fi adunată într-un nedefinit grup.
Pentru a vă permite să vă numiți grupurile așa cum doriți, am adăugat un sistem de aliasing. De exemplu, dacă declarați un grup cu @ helpgroupgroup, puteți adăuga un alias în acesta în configurație, astfel încât acesta să fie afișat, de exemplu, ca "Helpers and Tools". Acest lucru este util în special atunci când doriți să redenumiți nedefinit implicit în ceva mai prietenos, cum ar fi "general" sau orice altceva.
Dacă sunteți dispus să includeți SassDoc ca parte a procesului dvs. de desfășurare, veți fi încântați să știți că deja avem un plugin Grunt, un plugin Gulp și un plugin Broccoli, toate făcute de Pascal Duez. Folosirea lor este simplă dacă sunteți familiarizați cu modul de funcționare al fiecărui task runner:
/ * Gulp * / gulp.task ('sassdoc', funcție () return gulp .src ('cale / sursă'). ); / * Grunt * / grunt.initConfig (sassdoc: default: src: 'cale / spre / source', dest: 'cale / to / docs;
/ * Broccoli * / var sassdoc = necesită ("broccoli-sassdoc"); var docs = sassdoc (arbore, opțiuni); De asemenea, puteți adăuga aceleași opțiuni ca și CLI API-ul standard SassDoc, deci nu ezitați să citiți README din depozit pentru a afla mai multe despre cum să faceți acest lucru!
Dacă există un lucru care îmi place foarte mult în documentația de orice fel, este abilitatea de a merge direct la codul sursă. Prin urmare, nu este o surpriză pe care am adăugat-o Vizualizare sursă facilitate pentru SassDoc.
Deoarece acest lucru este strâns legat de vizualizare, este mai mult o caracteristică tematică decât ceva din SassDoc în sine. Pentru a spune pur și simplu, este nevoie de o cale de bază din fișierul de configurare, apoi link-uri către sursă sunt create folosind basePath +item.file.path, acesta din urmă fiind calculat de SassDoc. Din acest motiv, vă sugerăm să rulați întotdeauna SassDoc din rădăcina proiectului dvs. (vă ajută în multe cazuri).
Mă bucur că ai întrebat! Mai avem încă idei pentru viitorul SassDoc și suntem siguri că aveți niște opinii interesante. Nu-i păstrați pentru voi; împărțiți-le în depozit!
Între timp, lucrăm la:
@output adnotare, similar cu @întoarcere dar pentru amestecuri (# 133)