Share
Hace un par de semanas, presenté SassDoc en SitePoint cuando aún estaba en una fase temprana de desarrollo. Desde entonces, hemos lanzado al menos una versión principal y dos versiones secundarias, respectivamente: 1.0.0, 1.1.0 y 1.2.0. Hemos enviado varias características al hacerlo, así que pensé que sería una buena idea presentarlas..
Si aún no está familiarizado con SassDoc, permítame presentarlo.
SassDoc es para Sass lo que JSDoc es para JavaScript: una herramienta de documentación basada en comentarios dentro de sus archivos de trabajo. El escenario habitual es escribir comentarios para sus funciones, combinaciones y variables siguiendo las pautas de documentación, ejecute SassDoc desde la línea de comandos y el auge. Te has generado documentación..
Cuando introduje SassDoc por primera vez, la documentación generada estaba bien, supongo. Mientras tanto, realmente quería mejorar el diseño porque, cuando todo está dicho y hecho, si le dices a alguien que vas a generar documentos hermosos para ellos, es mejor que hagas las cosas bien y les muestres algo genial.!
Así que se me ocurrió un nuevo diseño basado en la oscuridad.
Esto levantó opiniones bastante atenuadas para ser honesto (incluso yo tenía mis reservas). Dicho esto, la belleza está en el ojo del espectador, por lo que guardé este bajo mi sombrero y encontré otro diseño muy inspirado en el nuevo diseño de Google..
espero que te guste!
Junto con esta nueva y brillante vista, agregamos un motor de búsqueda ligero basado en Fuse. Esto facilitará que las personas con un gran número de elementos documentados alcancen rápidamente el que están buscando sin tener que desplazarse para siempre. En la misma línea, hemos corregido la barra lateral en el tema predeterminado para que pueda vigilar la estructura de datos en todo momento..
En la versión 1.0.0, le hicimos posible marca La vista proporciona una ruta de acceso a un archivo de configuración que contiene información sobre su proyecto, como el nombre, la versión, la descripción, la licencia, etc. Lo bueno es que si tienes una paquete.json archivo (proyecto npm) a nivel raíz, lo usamos para que no tenga que duplicar la información de su proyecto para SassDoc. Que lindo.
En 1.2 queríamos llevar las cosas más lejos. Como waaay más allá. Nuestro objetivo era ofrecerle la posibilidad de utilizar sus temas personalizados y sus plantillas personalizadas (con su motor de plantillas favorito). Básicamente, queríamos entregarte los datos para que puedas hacer lo que quieras con ellos. Al igual que:
sassdoc src / folder destination / folder --theme my-awesome-theme
Nota: Cuando se configura el --tema Opción de la interfaz cli, SassDoc buscará un sassdoc-theme-foo paquete, entonces ./ foo, y finalmente foo.
Mientras tanto, no queríamos hacer las cosas demasiado difíciles de su parte, así que hicimos que nuestro genio de JavaScript Valérian Galliat construyera un motor de temática: Themeleon. Este es un proyecto independiente construido para SassDoc pero completamente independiente de él. Es un pequeño motor de temas de Node que se ejecuta con aproximadamente 100 líneas de JavaScript.
No está obligado a usar Themeleon para conectar su tema a SassDoc, aunque facilita el trabajo porque mantiene toda la suciedad técnica debajo del capó. Además, viene con una mezcla (tipo de complemento) para ambos motores de plantillas Swig (trago de temática) y Jade (tema-jade), para evitar que incluso tengas que hacer lo que viene después.
Valérian ha escrito una introducción en profundidad sobre cómo construir y usar tu propio tema, así que cubriré lo básico aquí..
Todo lo que tiene que hacer el tema es exponer una función que implementa la siguiente interfaz:
/ ** * @param string dest Directorio para representar el tema en. * @param objeto ctx Variables para pasar al tema. * @return promesa Una promesa / A + implementación. * / module.exports = function (dest, ctx) …;
Desde allí, Themeleon se encarga de todo y le permite escribir su tema sin molestarse en consideraciones de "bajo nivel", como el manejo de promesas, en bruto. fs llamadas, asegurándose de que existe el directorio de destino, y así sucesivamente.
Entonces, se trata de crear un paquete.json archivo que requiere algunas dependencias (incluyendo temática y su motor de plantillas, por ejemplo trago de temática, tema-jade o lo que sea). Así como un directorio que contiene un index.js archivo como se explica en los documentos. Luego, este archivo JavaScript describirá el proceso para generar la salida..
En nuestro tema por defecto usando trago de temática, Es tan simple como:
Accentsconagua
var themeleon = require ('themeleon') (). use ('swig'); module.exports = themeleon (__ dirname, function (t) t.copy ('asset'); t.swig ('views / documentation / index.html.swig', 'index.html');); ¡Eso es! Si planea crear su propio tema, le complacerá saber que hemos creado una placa de repetición para ayudarlo a comenzar. Ve y lee los documentos, escribe un par de líneas y estarás listo. Además, no dude en pedir cualquier ayuda.!
Una característica que realmente hemos estado esperando por un tiempo ahora es la capacidad de reunir sus artículos en grupos. Al principio, agrupamos artículos según su tipo: función, mezclar y variable. Al documentar una única API, estaba bien, pero cuando se ejecutaba SassDoc en proyectos más grandes, se sentía un poco apagado.
Por lo tanto, ahora puede utilizar el @grupo anotación seguida de una cadena para definir un grupo para un elemento gracias al gran trabajo de Fabrice Weinberg. Todos los elementos que comparten el mismo grupo se mostrarán en la misma sección. Mantenemos la agrupación de tipos, por lo que al final del día, funciona así: grupo > tipo > artículos. Mientras tanto, todos los artículos sin un @grupo la anotación se reunirá en una indefinido grupo.
Para permitirle nombrar a sus grupos de la forma que desee, agregamos un sistema de aliasing. Por ejemplo, si declara un grupo con ayudantes de grupo, puede agregarle un alias en la configuración para que se muestre como "Ayudantes y herramientas", por ejemplo. Esto es especialmente útil cuando desea cambiar el nombre de indefinido Grupo predeterminado en algo más amigable como "General" o lo que sea.
Si está dispuesto a incorporar SassDoc como parte de su proceso de implementación, le complacerá saber que ya tenemos un complemento Grunt, un complemento Gulp y un complemento de brócoli, todos hechos por Pascal Duez. Usarlos es sencillo si está familiarizado con la forma en que funciona cada corredor de tareas:
/ * 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 (árbol, opciones); También puede agregar las mismas opciones que la API CLI regular de SassDoc, así que no dude en leer el archivo README de los repositorios para obtener más información sobre cómo hacerlo.!
Si hay algo que realmente me gusta en la documentación de cualquier tipo, es la posibilidad de ir directamente al código fuente. Por eso no es de extrañar que hayamos añadido un ver fuente característica de SassDoc.
Debido a que esto está estrechamente relacionado con la vista, es más como una característica del tema que algo de SassDoc. En pocas palabras, necesita una ruta base desde el archivo de configuración, luego los enlaces a la fuente se crean usando basePath +item.file.path, siendo esta última computada por SassDoc. Por esa razón, le sugerimos que siempre ejecute SassDoc desde la raíz de su proyecto (esto ayuda en muchos casos).
Me alegra que hayas preguntado! Todavía tenemos muchas ideas para el futuro de SassDoc, y estamos seguros de que usted también tiene algunas opiniones interesantes. No los guardes para ti; Compártelos en el repositorio.!
Mientras tanto, estamos trabajando en:
@salida anotación, similar a @regreso pero para mixins (# 133)