Share
Il y a quelques semaines, j'ai présenté SassDoc chez SitePoint alors qu'il en était encore à ses débuts. Depuis lors, nous avons publié pas moins d'une version majeure et deux versions mineures, respectivement: 1.0.0, 1.1.0 et 1.2.0. Nous avons fourni un certain nombre de fonctionnalités, alors j’ai pensé que ce serait une bonne idée de les présenter..
Si vous ne connaissez pas encore SassDoc, permettez-moi de vous le présenter..
SassDoc est ce que JSDoc représente pour JavaScript: un outil de documentation basé sur les commentaires contenus dans vos fichiers de travail. Le scénario habituel consiste à écrire des commentaires pour vos fonctions, mixins et variables en suivant les instructions de la documentation, puis à exécuter SassDoc à partir de la ligne de commande et du boom. Vous avez vous-même généré de la documentation.
Lorsque j'ai introduit SassDoc pour la première fois, la documentation générée était satisfaisante, je suppose. En attendant, je voulais vraiment améliorer le design car, une fois que tout est dit, si vous dites à quelqu'un que vous allez générer de beaux documents pour lui, vous feriez mieux de bien faire les choses et de lui montrer quelque chose de grand.!
Alors je suis venu avec un nouveau design sombre.
Pour être honnête, cela a suscité des opinions assez mitigées (même si j'avais des réserves). Cela étant dit, la beauté est dans l'œil du spectateur. J'ai donc gardé celle-ci sous mon chapeau et proposé un autre design fortement inspiré du nouveau Google Design..
J'espère que tu aimes!
Parallèlement à cette nouvelle vue brillante, nous avons ajouté un moteur de recherche léger et flou basé sur Fuse. Cela permettra aux personnes ayant un grand nombre d’articles documentés d’atteindre rapidement l’objet recherché sans avoir à faire défiler les pages à jamais. Dans le même ordre d'idées, la barre latérale a été fixée dans le thème par défaut afin que vous puissiez garder un œil sur la structure de données à tout moment..
Dans la version 1.0.0, nous vous avons permis de: marque la vue en fournissant un chemin d'accès à un fichier de configuration contenant des informations sur votre projet, telles que le nom, la version, la description, la licence, etc. La chose intéressante est, si vous avez un package.json fichier (projet npm) au niveau racine, nous l’avons utilisé afin que vous n’ayez pas à dupliquer les informations de votre projet pour SassDoc. Donc c'est assez sympa.
En 1.2, nous voulions pousser les choses plus loin. Comme waaay plus loin. Notre objectif était de vous donner la possibilité d’utiliser vos thèmes et vos modèles personnalisés (avec votre moteur de modèles préféré). En gros, nous voulions vous transmettre les données afin que vous puissiez en faire ce que vous voulez. Ainsi:
sassdoc src / dossier destination / dossier --theme my-awesome-theme
Remarque: Lorsque vous définissez la --thème l’option de l’interface cli, SassDoc recherchera un sassdoc-theme-foo paquet, alors ./ foo, et enfin foo.
En attendant, nous ne voulions pas vous compliquer la tâche, alors nous avons demandé à notre génie JavaScript, Valérian Galliat, de construire un moteur de thématisation: Themeleon. Il s'agit d'un projet autonome construit pour SassDoc mais totalement indépendant de celui-ci. C'est un minuscule moteur de thème Node fonctionnant avec environ 100 lignes de JavaScript..
Vous n'êtes pas obligé d'utiliser Themeleon pour connecter votre thème à SassDoc, bien que cela facilite le travail, car il garde toute la saleté technique sous le capot. En outre, il est livré avec un mixin (sorte de plugin) pour les deux moteurs de template Swig (Thèmeon-swig) et Jade (Thèmeon-Jade), afin de vous éviter même de faire ce qui suit.
Valérian a écrit une introduction détaillée à la construction et à l'utilisation de votre propre thème. Je vais donc simplement couvrir les bases ici..
Tout ce que le thème doit faire est d’exposer une fonction implémentant l’interface suivante:
/ ** * @param chaîne dest Répertoire dans lequel le thème doit être rendu. * @param objet ctx Variables à transmettre au thème. * @retour promesse Une implémentation Promises / A +. * / module.exports = fonction (destination, ctx) …;
À partir de là, Themeleon se charge de tout et vous permet d’écrire votre thème sans vous soucier de considérations de "bas niveau", comme la gestion des promesses, les fs appels, en s'assurant que le répertoire de destination existe, etc..
Ensuite, il s’agit de créer un package.json fichier nécessitant des dépendances (y compris Thèmeon et votre moteur de template, par exemple Thèmeon-swig, Thèmeon-Jade ou peu importe). Ainsi qu’un répertoire contenant un index.js fichier comme expliqué dans la documentation. Ensuite, ce fichier JavaScript décrira le processus pour générer la sortie.
Dans notre thème par défaut en utilisant Thèmeon-swig, c'est aussi simple que:
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');); C'est tout! Si vous envisagez de créer votre propre thème, vous serez heureux de savoir que nous avons conçu un passe-partout pour vous aider à démarrer. Allez-y, lisez la documentation, écrivez quelques lignes et vous serez prêt à partir. Aussi, n'hésitez pas à demander de l'aide!
Une fonctionnalité que nous attendons avec impatience depuis un certain temps est la possibilité pour vous de regrouper vos éléments. Au début, nous avons regroupé les éléments en fonction de leur type: une fonction, mixin et variable. C'était très bien de documenter une seule API, mais lorsque SassDoc était utilisé sur des projets plus importants, cela semblait un peu gênant..
Ainsi, vous pouvez maintenant utiliser le @groupe Une annotation suivie d'une chaîne pour définir un groupe pour un élément grâce au travail remarquable de Fabrice Weinberg. Tous les articles partageant le même groupe seront affichés dans la même section. Nous conservons le groupe de types, donc à la fin de la journée, cela fonctionne comme suit: groupe > type > articles. En attendant tous les articles sans @groupe l'annotation sera réunie dans un indéfini groupe.
Pour vous permettre de nommer vos groupes comme vous le souhaitez, nous avons ajouté un système de crénelage. Par exemple, si vous déclarez un groupe avec @group helpers, vous pouvez ajouter un alias à celui-ci dans la configuration pour qu'il soit affiché comme "Helpers and Tools" par exemple. Ceci est particulièrement utile lorsque vous souhaitez renommer le indéfini groupe par défaut en quelque chose de plus convivial comme "Général" ou autre chose.
Si vous souhaitez intégrer SassDoc à votre processus de déploiement, sachez que nous avons déjà un plugin Grunt, un plugin Gulp et un plugin Broccoli, tous conçus par Pascal Duez. Leur utilisation est simple si vous connaissez le fonctionnement de chaque gestionnaire de tâches:
/ * Gulp * / gulp.task ('sassdoc', function () return gulp .src ('chemin / de / source') .pipe (sassdoc (dest: 'chemin / de / docs')); ) / * Grunt * / grunt.initConfig (sassdoc: défaut: src: 'chemin / vers / source', dest: 'chemin / vers / docs',);
/ * Brocoli * / var sassdoc = require ('broccoli-sassdoc'); var docs = sassdoc (arborescence, options); Vous pouvez également ajouter les mêmes options que l'API CLI standard de SassDoc. N'hésitez donc pas à lire le fichier README dans les référentiels pour en savoir plus sur la procédure à suivre.!
S'il y a une chose que j'aime vraiment dans la documentation, quelle qu'elle soit, c'est la possibilité d'aller directement au code source. Il n'est donc pas surprenant que nous ayons ajouté un voir la source fonction à SassDoc.
Parce que cela est étroitement lié à la vue, cela ressemble plus à une fonctionnalité de thème qu'à quelque chose de SassDoc lui-même. Pour le dire simplement, il faut un chemin de base à partir du fichier de configuration, puis des liens vers la source sont créés en utilisant basePath +item.file.path, ce dernier étant calculé par SassDoc. Pour cette raison, nous vous suggérons de toujours lancer SassDoc à partir de la racine de votre projet (cela aide dans de nombreux cas)..
Content que tu aies demandé! Nous avons encore de nombreuses idées pour l’avenir de SassDoc, et nous sommes certains que vous avez vous-même des opinions intéressantes. Ne les garde pas pour toi; partagez-les sur le référentiel!
En attendant, nous travaillons sur:
@sortie annotation, similaire à @revenir mais pour les mixins (# 133)