Share
Vor ein paar Wochen habe ich SassDoc in SitePoint vorgestellt, als es sich noch in einer frühen Entwicklungsphase befand. Seitdem haben wir nicht weniger als eine Haupt- und zwei Nebenversionen veröffentlicht: 1.0.0, 1.1.0 und 1.2.0. Wir haben dabei eine Reihe von Funktionen ausgeliefert, daher dachte ich, es wäre eine gute Idee, sie einzuführen.
Wenn Sie mit SassDoc noch nicht vertraut sind, können Sie es mir vorstellen.
SassDoc gibt an, was JSDoc für JavaScript ist: ein Dokumentationswerkzeug, das auf Kommentaren in Ihren Arbeitsdateien basiert. Das übliche Szenario besteht darin, Kommentare für Ihre Funktionen, Mixins und Variablen gemäß den Dokumentationsrichtlinien zu schreiben, SassDoc über die Befehlszeile und den Baum auszuführen. Sie haben selbst eine Dokumentation erstellt.
Als ich SassDoc zum ersten Mal vorstellte, war die generierte Dokumentation okay, schätze ich. In der Zwischenzeit wollte ich unbedingt das Design verbessern, denn wenn man alles gesagt und getan hat, wenn man jemandem sagt, dass man schöne Dokumente für ihn erstellen wird, sollte man die Dinge richtig machen und ihnen etwas Großes zeigen!
Also habe ich mir ein neues Dark-basiertes Design ausgedacht.
Um ehrlich zu sein (dies hatte sogar meine Vorbehalte), waren die Meinungen sehr abgeschwächt. Davon abgesehen liegt Schönheit im Auge des Betrachters, also habe ich diese unter meinem Hut behalten und mir ein anderes Design ausgedacht, das stark vom neuen Google-Design inspiriert wurde.
Ich hoffe du magst es!
Neben dieser brandneuen, glänzenden Ansicht haben wir eine leichte Fuzzy-Suchmaschine basierend auf Fuse hinzugefügt. Dies macht es Personen mit einer großen Anzahl dokumentierter Elemente einfacher, den gesuchten Artikel schnell zu erreichen, ohne für immer scrollen zu müssen. In gleicher Weise haben wir die Seitenleiste im Standarddesign festgelegt, sodass Sie die Datenstruktur jederzeit im Auge behalten können.
In Version 1.0.0 haben wir es Ihnen ermöglicht Marke In der Ansicht geben Sie einen Pfad zu einer Konfigurationsdatei an, die einige Informationen zu Ihrem Projekt enthält, z. B. Name, Version, Beschreibung, Lizenz usw. Die coole Sache ist, wenn Sie eine haben package.json Datei (npm-Projekt) auf Stammebene haben wir sie verwendet, damit Sie die Projektinformationen für SassDoc nicht duplizieren müssen. Das ist also ziemlich nett.
In 1.2 wollten wir die Dinge weiter vorantreiben. Wie waaay weiter. Unser Ziel war es, Ihnen die Möglichkeit zu geben, Ihre benutzerdefinierten Designs und Ihre benutzerdefinierten Vorlagen (mit Ihrer bevorzugten Vorlagen-Engine) zu verwenden. Grundsätzlich wollten wir Ihnen die Daten zur Verfügung stellen, damit Sie machen können, was Sie möchten. So wie:
sassdoc src / ordner ziel / ordner --theme my-awesome-theme
Hinweis: Wenn Sie das einstellen --Thema Bei Auswahl der CLI-Schnittstelle sucht SassDoc nach einem Sassdoc-Theme-Foo dann Paket ./ foo, und schlussendlich foo.
In der Zwischenzeit wollten wir es Ihnen nicht zu schwer machen, also ließen wir unser JavaScript-Genie Valérian Galliat eine Theming-Engine bauen: Themeleon. Dies ist ein eigenständiges Projekt, das für SassDoc erstellt wurde, aber völlig unabhängig davon ist. Es ist eine winzige Node-Design-Engine mit etwa 100 JavaScript-Zeilen.
Sie sind nicht verpflichtet, Themeleon zu verwenden, um Ihr Design mit SassDoc zu verbinden, obwohl dies die Arbeit erleichtert, da es den gesamten technischen Schmutz unter der Haube hält. Außerdem wird ein Mixin (eine Art Plugin) für beide Template-Engines Swig (themeleon-swig) und Jade (Themeleon-Jade), um zu verhindern, dass Sie das tun müssen, was als nächstes kommt.
Valérian hat eine ausführliche Einführung in das Erstellen und Verwenden Ihres eigenen Themas geschrieben. Ich werde hier nur die Grundlagen erläutern.
Alles, was das Thema tun muss, ist eine Funktion bereitzustellen, die die folgende Schnittstelle implementiert:
/ ** * @param string dest Verzeichnis, in dem das Design dargestellt werden soll. * @param object ctx Variablen, die an das Design übergeben werden. * @return Versprechen Eine Implementierung von Promises / A +. * / module.exports = Funktion (dest, ctx) …;
Von dort aus übernimmt Themeleon alles und ermöglicht Ihnen, Ihr Thema zu schreiben, ohne sich mit "Low-Level" -Überlegungen wie Versprechungshandling, Rohmaterial beschäftigen zu müssen fs Anrufe, um sicherzustellen, dass das Zielverzeichnis vorhanden ist, und so weiter.
Dann geht es nur noch darum, eine package.json Datei, die einige Abhängigkeiten erfordert (einschließlich themeleon und deine Template Engine zum Beispiel themeleon-swig, Themeleon-Jade oder Wasauchimmer). Sowie ein Verzeichnis mit einem index.js Datei wie in den Dokumenten beschrieben. Diese JavaScript-Datei beschreibt dann den Prozess zum Generieren der Ausgabe.
In unserem Standarddesign verwenden Sie themeleon-swig, es ist so einfach wie:
Accentsconagua
var themeleon = required ('themeleon') (). use ('swig'); module.exports = themeleon (__ dirname, function (t) t.copy ('assets'); t.swig ('views / documentation / index.html.swig', 'index.html');); Das ist es! Wenn Sie planen, Ihr eigenes Thema zu erstellen, werden Sie sich freuen zu wissen, dass wir eine Boilerplate für den Einstieg entwickelt haben. Lesen Sie die Dokumente und schreiben Sie ein paar Zeilen. Gerne können Sie auch um Hilfe bitten!
Eine Funktion, auf die wir uns seit einiger Zeit wirklich gefreut haben, ist die Möglichkeit, Ihre Artikel in Gruppen zusammenzufassen. Zuerst haben wir die Artikel nach ihrem Typ gruppiert: Funktion, mixin und Variable. Bei der Dokumentation einer einzelnen API war dies in Ordnung, aber wenn SassDoc für größere Projekte ausgeführt wurde, fühlte es sich ein wenig ab.
Somit können Sie jetzt die @Gruppe Anmerkung, gefolgt von einer Zeichenfolge, um eine Gruppe für einen Artikel zu definieren, dank der großartigen Arbeit von Fabrice Weinberg. Alle Elemente, die sich in derselben Gruppe befinden, werden im selben Abschnitt angezeigt. Wir behalten die Typgruppierung bei, so dass es am Ende des Tages so funktioniert: Gruppe > Art > Artikel. Inzwischen sind alle Artikel ohne @Gruppe Die Anmerkung wird in einer Sammlung gesammelt nicht definiert Gruppe.
Damit Sie Ihre Gruppen beliebig benennen können, haben wir ein Aliasing-System hinzugefügt. Zum Beispiel, wenn Sie eine Gruppe mit deklarieren @group-Helfer, Sie können ihm in der Konfiguration einen Alias hinzufügen, der beispielsweise als "Helfer und Tools" angezeigt wird. Dies ist besonders nützlich, wenn Sie die Datei umbenennen möchten nicht definiert Standardgruppe in etwas freundlicheres wie "Allgemein" oder was auch immer.
Wenn Sie bereit sind, SassDoc als Teil Ihres Bereitstellungsprozesses zu integrieren, werden Sie erfreut sein, dass wir bereits ein Grunt-Plugin, ein Gulp-Plugin und ein Broccoli-Plugin von Pascal Duez besitzen. Die Verwendung ist einfach, wenn Sie mit der Funktionsweise der einzelnen Task-Läufer vertraut sind:
/ * 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', Ziel: 'path / to / docs',);
/ * Broccoli * / var sassdoc = erfordern ('broccoli-sassdoc'); var docs = sassdoc (Baum, Optionen); Sie können auch die gleichen Optionen wie die reguläre SassDoc-CLI-API hinzufügen. Lesen Sie daher die README-Datei aus den Repositorys, um mehr darüber zu erfahren!
Wenn es eine Sache gibt, die ich an Dokumentation jeglicher Art wirklich mag, ist es die Möglichkeit, direkt zum Quellcode zu gelangen. Es ist daher keine Überraschung, dass wir eine hinzugefügt haben Quelltext anzeigen Funktion für SassDoc.
Da dies eng mit der Ansicht verknüpft ist, ähnelt es eher einem Design-Feature als etwas von SassDoc. Um es einfach auszudrücken, benötigt es einen Basispfad aus der Konfigurationsdatei. Anschließend werden Verknüpfungen mit der Quelle erstellt basePath +Artikel.Datei.Pfad, Letzteres wird von SassDoc berechnet. Aus diesem Grund empfehlen wir Ihnen, SassDoc immer von der Wurzel Ihres Projekts aus auszuführen (dies hilft in vielen Fällen)..
Schön, dass Sie gefragt haben! Wir haben noch viele Ideen für die Zukunft von SassDoc, und wir sind sicher, dass Sie selbst einige interessante Meinungen haben. Bewahre sie nicht für dich auf; teile sie auf dem Repository!
Inzwischen arbeiten wir an:
@Ausgabe Anmerkung, ähnlich wie @Rückkehr aber für mixins (# 133)