Introducción a sphinx-js, una mejor forma de documentar proyectos JavaScript grandes

30 noviembre, 2017 2:50 por

Esta es una traducción del artículo original publicado en el blog de Mozilla Hacks.

Hasta ahora, no ha habido una buena herramienta para documentar proyectos JavaScript grandes. JSDoc, durante mucho tiempo el único contendiente, tiene algunas características interesantes:

  • Un bien definido conjunto de etiquetas para describir estructuras comunes.
  • Herramientas como Closure Compiler que se engancha en estas etiquetas.

Pero el resultado siempre es una mera lista alfabética de todo en tu proyecto. JSDoc aplana y revuelve tus funciones, dejando a los nuevos usuarios a inferir sus relaciones y ordenarlas mentalmente en grupos comprensibles. Si bien puedes salirte con la tuya con librerías pequeñas, esto falla tristemente con otras más grandes como Fathom, que tiene nuevos conceptos complejos que explicar. Lo que he buscado en el manual de Fathom fue la capacidad de organizarlo lógicamente, intercalar prosa explicativa con documentos extraídos, y agregar secciones completas que no son más que una descripción conceptual y, sin embargo, enlazan con el resto del trabajo1.

El mundo de Python ha favorecido Sphinx por mucho tiempo, una herramienta de documentación con soporte para muchos formatos de lenguages y formatos de resultados, junto con indexación de primera clase, generación de glosarios, búsqueda, y referencia cruzada. Las personas han escrito libros enteros sobre ella. A través de complementos soporta de todo, desde diagramas Graphviz hasta videos de YouTube. Sin embargo, su soporte de JavaScript siempre ha carecido de la capacidad de extraer documentos desde código.

Ahora sphinx-js agrega esa capacidad, dando a los desarrolladores JavaScript lo mejor de ambos mundos.

sphinx-js consume comentarios y etiquetas JSDoc estándares – no tienes que hacer nada raro a tu código fuente (de hecho, se delega la conversión y extracción al JSDoc mismo, haciéndolo resistente a cambios futuros). Sólo tienes que hacer que Sphinx inicialice un directorio docs en la raíz de tu proyecto, activar sphinx-js como un complemento, y luego escribir tus documentos como quieras usando reStructuredText simple. Cuando llega el momento de llamar a alguna documentación extraída, usa un de las directivas especiales de sphinx-js, modelada según el ejemplo de autodoc centrada en Python. El ejemplo más sencillo se ve así:

.. autofunction:: linkDensity

Esto buscaría y encontraría esta función…

/**
 * Return the ratio of the inline text length of the links in an element to
 * the inline text length of the entire element.
 *
 * @param {Node} node - The node whose density to measure
 * @throws {EldritchHorrorError|BoredomError} If the expected laws of the
 *     universe change, raise EldritchHorrorError. If we're getting bored of
 *     said laws, raise BoredomError.
 * @returns {Number} A ratio of link length to overall text length: 0..1
 */
function linkDensity(node) {
  ...
}

Y genera un bloque bien formateado como esto:

Ejemplo js-sphinx

Sphinx empieza a mostrar su flexibilidad cuando quieres hacer algo como agregar una serie de ejemplos largos. En lugar de abarrotar el código fuente alrededor de linkDensity, el material adicional puede vivir en los archivos reStructuredText que comprende tu manual:

.. autofunction:: linkDensity
   
   Cualquier cosa que escribas aquí será agregado a la descripción de la función
   justo después de su valor de retorno. ¡Es un buen lugar para ejemplos extensos!

También hay una directiva sphinx-js para clases, ya sea cualquier tipo de ECMAScript 2015 o de las funciones-como-constructor clásicas decoradas con @class. Opcionalmente, puede tierar sobre los miembros de la clase, documentando a como avanza. Puedes controlar el orden, activar o desactivar miembros privados, o incluir o excluir miembros específicos por nombre – todos los bien planeados casos inusuales que Sphinx soporta en código Python. Aquí hay un ejemplo del mundo real que muestra uno pocos métodos realmente públicos mientras esconde algunos métodos “friend” que son específicos del framework:

.. autoclass:: Ruleset(rule[, rule, ...])
   :members: against, rules

Ejemplo de Sphinx con clases

Yendo más allá de las convenciones bien establecidas de Python, sphinx-js suporta referencias a entidades JS que de otro modo colisionaría: por ejemplo, un foo que es un método estático en un objeto y otro foo que es un método instancia en el mismo. Esto lo hace usando una variante de los namepaths de JSDoc. Por ejemplo…

  • someObject#foo es el método instancia.
  • someObject.foo es el método estático.
  • Y someObject~foo es un miembro interno, el tercer tipo posible superposición.

Ya que JSDoc está haciendo el análisis detrás de escena, aprovechamos su entendimiento de estas complejidades de JS.

Claro, JS es un lenguaje de indentación dura, así que las cosas se vuelven profundas y oscuras a toda prisa. ¿Quién quiere escribir esta ruta completa para documentar innerMember?

some/file.SomeClass#someInstanceMethod.staticMethod~innerMember

¡Qué feo! Afortunadamente, sphinx-js indexa todas estas rutas de objetos usando un árbol de sufijos, así que puedes usar cualquier sufijo que refiera sin ambigüedad a un objeto. Es probable que digas sólo innerMember. O, si hay 2 objetos llamados “innerMember” en tu código base, se podría eliminar la ambigüedad diciendo staticMethod~innerMember y así, moviendo a la izquierda hasta que tengas un único resultado. Esto te da brevedad y, como bono, te ahorra tener que tocar documentos a medida que las cosas se mueven alrededor de tu código base.

Con la madurez y poder de Sphinx, respaldado por las convenciones sintácticas y maquinaria analítica probada de JSDoc, sphinx-js es una excelente manera de documentar cualquier gran proyecto JS. Para empezar, revisa la documentación. O, para un ejemplo de gran escala, revisa la documentación de Fathom. Una página particularmente jugosa es la Referencia de Regla y Conjunto de Reglas, que intercala párrafos tutoriales con documentación de clases y funciones; su código fuente está disponible detrás de un enlace en la esquina superior derecha, como para todas las páginas.

Esperamos tus historias de éxito y reporte de errores — ¡y al próximo crecimiento de la documentación rica, comprensible y organizada de JS!


1JSDoc tiene tutoriales, pero éstos son poco más que simples páginas HTML. No tienen una capacidad particular para realizar enlaces cruzados con el resto de la documentación ni para llamar a los comentarios extraídos.

The following two tabs change content below.

AngelFQC

Web Developer at BeezNest Latino
Ingeniero de Sistemas y Computación. Desarrollador PHP. Mozilla Peru. Chamilo LMS Developer.

Compartir artículo:

Join the discussion at foro.mozilla-hispano.org

  • ¡Participa!

    Firefox Friends »
    Agrega botones de Firefox en tu sitio web y comparte tu amor por Mozilla Firefox.
    Armada alucinante »
    Ayuda a otros usuarios en Twitter.
    Colabora con la comunidad »
    En Mozilla lo importante son las personas. Descubre cómo puedes colaborar.

    Boletín Firefox

    Suscríbete al boletín de novedades de Firefox.

  • Descargas

    Descarga los programas de Mozilla.

    Lo más visto

    cc-by-sa