Yahoo! Interfaz de usuario de blog (YUIBlog)

Zottmann Carlo Tema Dana para YUI Doc.

Me gusta usar YUI Doc. para todas mis necesidades documentación de JavaScript. He descubierto que funciona bien para la documentación de la vainilla o el código JS llanura jQuery - no es sólo para YUI basada proyectos.

Yo era escéptico al principio, ya que tienden a escribir más jQuery que el código de YUI. Fue una agradable sorpresa al descubrir que YUI Doc. integrar fácilmente en mi flujo de trabajo y podrían generar documentación útil para mis proyectos no YUI. Claro, tiene algunas expectativas con respecto a un proyecto, etc estructura de archivos, pero ninguna de estas expectativas son motivos para desistir de mí. Por otro lado, se trata de un sistema de luz y lo puedo poner en marcha en poco tiempo.

Contar con una herramienta de análisis el código fuente y documentación de la versión automágicamente calidad para mí es grande - no sólo para buscar rápidamente la función, etc llamadas más adelante, para mí es un valor añadido de dos maneras:

En primer lugar, el código de documento de cualquier manera por mi propio bien - probablemente voy a tener que volver a visitar en unos meses y que debería ser capaz de recoger rápidamente. No tener documentación significa cierta confusión en el futuro, que no es una idea que quiero dar a mis clientes.

En segundo lugar, la documentación de código podría ser un poco más de un concepto abstracto para un cliente: Puedo decirle que está ahí, pero la única manera que puede "probar" mi reclamo es por el disparo de mi editor y señalar con el dedo a los bloques de comentarios en mi código. Que realmente no se ven muy impresionante - en el peor, se ven como una excusa pena por "adecuada" la documentación.

Sin embargo, encendiendo mi navegador y mostrar los comentarios mismo analizada y procesada por YUI Doc - limpio, brillante, coherente - ahora que el código profesional diabluras allí, la gente.

(Si usted acaba de ocurrir "código documentado en un wiki es tan bueno y menos de una molestia", por favor, acepte mis palmas de golf triste - es todo. No porque)

Por desgracia, yo no soy un fan de la piel de base YUI Doc.. Cuando la mano sobre un pedazo de código bien documentado a mis clientes, quiero que vean el código bien documentado, para mí, el tema YUI Doc por defecto no brillan lo suficiente.

Mirando alrededor de temas de reemplazo no pude encontrar ninguno. Hace unas pocas semanas, así que decidí escribir mi propia - Dana . Aquí está un ejemplo:

Como se puede ver arriba, he generado el conocido YUI documentación de la API como un ejemplo. Aquí está la documentación original YUI - y aquí es lo mismo una documentación muy deportivo el nuevo tema de Dana .

Me parece el más agradable este último a la vista - Espero que usted está de acuerdo! Haga clic en un poco, ver algunas de las documentaciones de clase para una comparación más a fondo, jugar con los filtros, se siente el plástico de lujo y económicas, por debajo.

Hasta ahora, he recibido muchos comentarios positivos. Mis clientes aprecian la mirada limpia, y me siento mejor con respecto a la presentación más profesional de los trabajos que he puesto en mis proyectos, hasta el margen de beneficio generado.

¿Cómo se construyó

Empecé a escribir Dana por tirar todos los bits de código HTML dentro de la omisión YUI Doc. plantillas, volver a empezar desde cero y capas de mis marcas propias en la parte superior de los bloques básicos de YUI Doc. Cheetah código. (Cheetah es el sistema de plantillas Python utilizados por YUI Doc.. La # bloques que encontrarás en las plantillas contienen código Python ejecutado por Cheetah.)

Para ser honesto, averiguar lo que está pasando en las plantillas no era realmente un paseo por el parque - YUI Doc. las plantillas no están anotados, y orientada a conseguir que un recién llegado al sistema tomó algo de tiempo. Cuando tuve la sensación de que entiende la lógica de la estructura y los guepardos, que destruyó el resto de las marcas, reemplazándolo con algunas construcciones muy sencillas, y construido en la parte superior de esta. Me tomó un tiempo.

Si usted piensa acerca de cómo escribir sus propios temas, me gustaría recomendar ya sea a través de Dana main.tmpl como punto de partida, o mirando el formato correcto original main.tmpl . Muchos bothans murieron para lograr que esta plantilla.

Yo no soy diseñador, he tratado de mantener la apariencia simple y claro sin la adición de muchas campanas y silbidos.

Construido en extras

He tomado la libertad de la aplicación de una pantalla (en mi humilde opinión) mejor de los parámetros de tipo de objeto: si varios parámetros se pasan como las propiedades en un solo objeto, sólo que el objeto se mostrará como un parámetro en las columnas de las tablas en primer lugar.

A modo de ejemplo, digamos que está documentando un método espera un parámetro de objeto de tipo que contiene tres propiedades:

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

Así es como este método se muestra en la documentación generada:

Tema por defecto: method( obj.param1, obj.param2, obj.param3 )
tema Dana: method( obj )

Para un ejemplo de la vida real, consulte la documentación de eventos s 'YAHOO.widget.DataTable .

Me parece que este tratamiento hace que la salida más conciso.

Requisitos

Dana requiere uno de los más Doc. YUI se basa , por ejemplo, construir 50 funciona bien - pero no va a trabajar con YUI Doc. 1.0.0b1.

Instalación / uso

Supongo que tienes YUI Doc. en marcha y funcionando en este momento. Sólo tienes que descargar Dana de GitHub , descomprimirlo, y decirle yuidoc.py usarlo a través de la -t/--template opción.

Palabras de clausura

Dana es todavía un trabajo en progreso, hay algunas cuestiones menores a la izquierda, por ejemplo, con algo de HTML code los bloques que salen demasiado amplia. No se trata de hacer frente automáticos para mí, pero su kilometraje puede variar.

Para aquellos lectores que, como yo, tener vértigo ante la idea de apoyar Markdown en YUI Doc. como yo (pista, pista), echa un vistazo a Occidente YUI Mike tenedor Doc. que añade exactamente eso. Mientras esperamos una nueva versión original Doc. YUI, quiero decir; *. Tos) *

Usted encontrará Dana en GitHub . Si usted está tan inclinado, usted puede descargar la última versión estable como tgz / zip , también. Si encuentra algún error, por favor cree un ticket .

Dana es de doble licencia de MIT y el proyecto GNU GPL v2. Ha sido probado en Safari 5 (OSX), FF3.6 (OSX), IE8 (WinXP).

Buscar conversaciones: Bloglines | technorati

Compartir y ampliar: Marcar con del.icio.us | Digg él! | reddit!