Egyszerű módszer a Sass-kód dokumentálására

A CSS egyre bonyolultabb. A Sass rengeteg CSS-problémát megold, de valószínűleg némi extra bonyolultságot is jelent a játékban. A Sass kód dokumentálása ugyanolyan létfontosságú, mint a szokásos CSS dokumentálása, ha nem is annyira. Ez nemcsak a következő fejlesztő számára fontos, de így hat hónap múlva is megértette saját kódját.

SassDoc az, hogy Sass-nak mi a JSDoc a JavaScript-nek. Az ötlet egyszerű: dokumentálja a kódot úgy, hogy sajátos módon megjegyzéseket ír be, futtat néhány rövid parancssori kódot, majd varázslatosan generál néhány gyönyörű dokumentációt. Hát nem szép?

Pascal Duez, Valérian Galliat, Fabrice Weinberg és én ezen a projekten dolgoztunk, és nem lehetünk boldogabbak annak, amit eddig kitaláltunk. Az egyik legfontosabb prioritásunk a SassDoc méretezhetőségének megőrzése, így alapvetően bármely Sass projektben használható. Kis oldal? Nincs mit. Hatalmas kódbázis? Téged fedeztek.

És ha nem vagy elégedett azzal, amit a dobozon kívül nyújtunk, ne aggódj - a SassDoc teljes mértékben bővíthető és tematizálható. A Guardian Style Sheets (Guss), a Bourbon és a Neat már beugrott, és áthelyezte dokumentációját a SassDoc-ba, szóval mire vársz?

A SassDoc által működtetett dokumentáció több szakaszban zajlik - amelyek többsége láthatatlan a végfelhasználó (Ön) számára:

  • Az elemző a forrásmappából származó összes fájlt végigjárja, hogy megragadja a SassDoc-kompatibilis megjegyzéseket
  • Az elemző létrehoz egy adatfát
  • Ugyanakkor a célmappa generálódik (újra)
  • Ha erre kérik, az adatfa tovább bővül, hogy további szolgáltatásokat nyújtson (kereszthivatkozások az elemek között, Markdown leírások, sorrend és így tovább)
  • Az adatstruktúra átkerül a témához
  • A téma a célmappában jeleníti meg
  • Olyan boldog vagy, mint egy egyszarvú

Szöveges megjegyzések

A SassDoc használatának megkezdése ugyanolyan egyszerű, mint megjegyzések írása a Sass fájlokba. Most a SassDoc képes funkciókat, mixeket, változókat és helyőrzőket dokumentálni inline megjegyzésekkel ( /// ) vagy C-stílusú megjegyzések ( / ** * / ).

Írjon néhány megjegyzést JSDoc formában minden egyes „elemhez”, amelyet dokumentálni szeretne. Például:

/// Baseline for all margins and gaps on the site /// @group configuration /// @access public /// @type Number $baseline: 1.5em;/// Centre a block to make it a container /// @group helpers /// @param {Number} $max-width - Max width for the container /// @require $baseline /// @output 'max-width', 'margin' and 'width' @mixin center($max-width: 1170px) { max-width: $max-width; margin: 0 auto $baseline; width: 100%; }

Miután írt ilyen megjegyzéseket minden dokumentálni kívánt elemhez, csak a SassDoc programot kell futtatnia a kódalapon. Először telepítse a SassDoc programot:

npm install sassdoc -g

Ezután futtassa a kódján (beviteli mappa), és adja meg, hol kell elkészíteni a dokumentációt (kimeneti mappa):

sassdoc /assets/scss docs

Számos lehetőséget adhat át - beleértve a konfigurációs fájl elérési útját (JSON vagy YAML) a --config , így testreszabhatja a nézetet. Az összes rendelkezésre álló lehetőség megtalálható a hivatalos dokumentációban.

A ThemesSassDoc egy alapértelmezett témát biztosít, amely készen áll a doboz használatára. Leginkább egy kibővíthető vagy összecsukható oldalsávból áll, és egy fő tartalmi terület mellett helyezkedik el, ahol az összes elem megjelenik.

Mivel valószínűleg ez a téma a leggyakrabban használt, sok extra funkcióval bővítettük, többek között:

  • Ügyféloldali keresőmotor
  • Minden cikkhez egy 'forrás megtekintése' link, amely egy online tárolóhoz vezet
  • Bővíthető oldalsáv a csoportok kezeléséhez
  • A csoportok egyedi nevének meghatározása
  • Csak nyilvános / privát elemek megjelenítésének képessége, valamint álnevek elrejtése és megjelenítése
  • Az egyes elemek tartalmának megjelenítésének képessége (függvények, mixek, helyőrzők és így tovább)
  • Egyedi kedvenc ikon meghatározásának képessége
  • A projektre vonatkozó információk JSON fájlon keresztüli megjelenítése (például csomag.json )

Theming motor

Tudjuk, hogy a SassDoc alapértelmezett témája nem biztos, hogy mindenkinek tetszik vagy megfelel. Ezért tettük a SassDoc-ot teljesen tematizálhatóvá, hála egy erőteljes kis tematikus motornak, amelyet kifejezetten a SassDoc számára építettünk, Temeleon .

A téma felépítése egy kis időt vesz igénybe, de meglehetősen egyszerűnek kell lennie, különösen, ha a Yeoman témagenerátort használja. Ebben az esetben arról van szó, hogy megválaszolunk néhány kérdést, hozzáadunk egy kis kedvenc sablonmotort (Swig, Jade, Mustache, Nunjucks ...), és néhány CSS-t teszünk a tetejére.

Ha azt szeretné, hogy a témája egy kicsit fejlettebb legyen, a SassDoc olyan eszközök gyűjteményét is kínálja, amelyeket bármilyen téma importálhat és használhat. Szeretné, ha a leírásokat Markdownba írnák? Megvan. Hasznos álneveket szeretne megadni a csoportnevekhez? Lehetséges az extra eszközökkel. Akár saját annotációit is meghatározhatja. Emellett annak érdekében, hogy segítsünk Önnek, amikor saját témáját készíti, létrehoztunk egy „üres” témát, amelyhez számos megjegyzés tartozik, amelyek elmagyarázzák, mit kell tennie.

Harmadik fél integrációja

Miután elkészült a témád, az npm-en keresztül csomagolhatod a világ számára. Használni a sassdoc-theme- * a névminta azt jelenti, hogy más fejlesztők a SassDoc-alapú dokumentációikhoz egyszerűen felhasználhatják --téma opció a CLI-től (vagy téma konfigurációs fájlból). A Neat és a Vulcan keretrendszerek már felépítették saját témáikat, amelyeket Ön is használhat.

Ha be akarja vonni a SassDoc-ot a telepítési folyamatba, létrehoztunk egy Grunt, Gulp és Broccoli plugint. Alternatív megoldásként használhatja a nyers adatokat vagy a Node API-t - bármi lebegjen a hajón.

Például a Grunting SassDoc valószínűleg így néz ki:

grunt.initConfig({ 'sassdoc': { 'default': { 'src': 'path/to/sass', 'dest': 'path/to/docs' } } });

A SassDoc egyszerű, ugyanakkor hatékony dokumentációk létrehozásával kívánja áthidalni az API-k, keretrendszerek, könyvtárak, készítők és fejlesztők közötti szakadékot. A jövőben több dolgot is dokumentálhatunk, beleértve a CSS-választókat, @import szabályok vagy akár a BEM módszertana.

Ha történetesen épít egy témát, segítségre van szüksége, vagy csak meg szeretné osztani a szeretetet, bátran vegye fel a kapcsolatot @SassDoc_ Twitteren.

Szavak: Hugo Giraudel

Hugo Giraudel a Teknolog.io . Ez a cikk először itt jelent meg net magazin .

Mint ez? Olvassa el ezeket!