Hacker le template de ASDoc pour utiliser Google Prettify

ASDoc est basé sur un template utilisant de nombreux fichiers xsl, js, html etc.

Le répertoire par défaut du template de ASDoc se trouve dans le répertoire sdk 3.0.0/asdoc/templates du Flex SDK 3. Pour ma part pour créer mon propre template pour ASDoc j'ai copié ce répertoire dans le repository SVN de mon framework pour éviter tout soucis. Vous pouvez bien entendu modifier directement les sources du template de ASDoc fourni dans le SDK de Flex 3 mais bon.... en général ce n'est pas trop conseillé ;)

Détaillons maintenant la procédure pour transformer ASDoc :

1 - Télécharger Google Code Prettify

Pour cela il suffit de récupérer la dernière version disponible sur Google Code : Google Prettify sur Google Code.

Ensuite il suffit de placer les 2 fichiers prettify.js et prettify.css à la racine du répertoire template. Vous pouvez ensuite personnaliser comme vous le désirez les couleurs des mots clés dans votre code en éditant simplement la feuille de style contenue dans le fichier "prettify.css".

2 - Modifier le fichier asdoc.js du répertoire template de ASDoc.

Avec n'importe quel éditeur de texte (JSEclipse ou NotePad++ par exemple) vous cherchez la fonction configPage() dans le fichier asdoc.js et il suffit d'ajouter ensuite à la fin de la fonction l'instruction prettyPrint() ; :

function configPage()
{
   // ... asdoc code here
 
    prettyPrint() ;
}

Cette méthode est invoquée lors de l'appel de l'événement window.onLoad dans chacune des pages de la documentation.

3 - Modifier le fichier adoc-util.xsl.

Tout d'abord il faut faire une recherche dans le fichier pour trouver l'élément XSL : getStyleLink. Ce noeud XSL contient les définitions des feuilles de style utilisées dans les pages HTML de la documentation. Il suffit donc d'ajouter dans ce noeud le tag suivant :

<xsl:template name="getStyleLink">
 
         ....
 
        <xsl:element name="link">
              <xsl:attribute name="rel">stylesheet</xsl:attribute>
              <xsl:attribute name="href">
              <xsl:value-of select="$baseRef"/>prettify.css</xsl:attribute>
              <xsl:attribute name="type">text/css</xsl:attribute>
        </xsl:element>   
 
        </xsl:otherwise>
    </xsl:choose>
</xsl:template>

En cas de doute vous pouvez consulter le fichier modifier sur le SVN de VEGAS : asdoc_util.xsl modifié

Ensuite il faut faire une nouvelle recherche dans le fichier pour trouver l'élément XSL avec l'identifiant : getTitleScript. Ce noeud contient les appels des scripts Javascript externes nécessaires dans l'application. Nous rajoutons donc comme pour les balises de style le code suivant :

<script language="javascript" type="text/javascript">
       <xsl:attribute name="src">
            <xsl:value-of select="$baseRef"/>
             <xsl:text>prettify.js</xsl:text>
        </xsl:attribute>
</script>

Vous pouvez ajouter cet élément juste avant l'élément qui permet de gérer le chargement du fichier asdoc.js.

Conclusion en tout genre

Résultat des opérations... Voici quelques petits exemples en parcourant la documentation de la version AS3 de VEGAS mon framework opensource :

Bon pour le moment j'ai pas encore eu le temps de totalement personnaliser la charte graphique de la documentation de VEGAS. Mais la possibilité d'afficher du code avec la colorisation syntaxique qu'il faut, c'est tout de même une bonne chose ;)

Pour utiliser Google Prettify dans votre Javadoc il faut donc changer très légèrement vos habitudes. Il faut à présent remplacer les balises <code> et <listing> de ASDoc avec respectivement les balises <code class="prettyprint"> et <pre class="prettyprint">, exemple :

package vegas.core
{
	import system.ISerializable;
	import system.Reflection;
 
	import vegas.logging.ILogable;
	import vegas.logging.ILogger;
	import vegas.logging.Log;	
 
	/**
	 * CoreObject offers a default implementation of the IFormattable, IHashable and ISerializable interfaces.
	 * <p>
	 * <pre class="prettyprint">
	 * import vegas.core.CoreObject ;
	 *  
	 * var core:CoreObject = new CoreObject() ;
	 * trace("> core : " + core) ;
	 * trace("> hashcode : " + core.hashCode()) ;
	 * trace("> toSource : " + core.toSource()) ;
	 * </pre>
	 * </p>
	 * @author eKameleon
	 * @version 1.0.0.0
	 */
	public class CoreObject extends Object implements IFormattable, IHashable, ILogable, ISerializable
	{
 
		/**
		 * Creates a new <code class="prettyprint">CoreObject</code> instance.
		 */
		function CoreObject() 
		{
		    _logger = Log.getLogger( Reflection.getClassPath(this) ) ;
		}
 
                // etc...
 
	}
 
}

Voici le résultat du code précédent : vegas.core.CoreObject

A noter pour ceux que cela intéresse que j'ai placé dans le SVN AS3 de VEGAS ma tache ANT qui me permet de générer ma documentation via ASDoc : http://svn1.cvsdude.com/osflash/vegas/AS3/trunk/build/asdoc/

Pour finir... faut bien entendu avant de vous quitter que je vous parle des petits points noirs de ASDoc... ASDoc est vraiment très pratique pour créer de la documentation mais franchement je trouve que le choix de Adobe pour un template super compliqué rempli de tas de fichiers XSL n'est pas forcément des plus judicieux. Je trouve franchement très lourde la gestion des éléments du template par des fichiers XSL vraiment "trop fourni" !

Ensuite... ASDoc n'est vraiment pas stable... Il faut faire énormément attention en créant la documentation car de nombreux problèmes apparaissent lors de la compilation de la documentation. Par exemple :

  • Problème avec les @ dans la documentation.. exemple écrire un mail test@test.com dans un script entraîne des instabilités et des oublis dans la documentation.
  • Coller dans une boucle for le symbole < ... exemple for( var i:uint = 0 ; i<n. Ici la documentation va arrêter le parsing après le <. Il faut absolument aérer le code et ne pas coller le caractère <.
  • L'Utilisation de certains caractères UTF8 pour valeur des propriétés des classes (voir par exemple mon hack de la classe vegas.string.UnicodeChar avec ce code source pas très propre pour le coup ! J'ai du rentrer les valeurs de mes constantes dans des Array pour éviter les bugs de ASDoc :()
  • Pour écrire dans un script <?php .. il faut utiliser la notation html &...
  • Problème avec l'utilisation du caractère * dans les exemples et les bouts de code : ... style trace( "vegas.errors.*" ) ; ..

Il va falloir que j'aille faire un tour du côté de la bug liste de Flex pour voir si on peut leur faire remonter les erreurs (qu'ils doivent sûrement déjà connaître...)

Sinon malgré ces petits problèmes, le rendu HTML de ASDoc reste vraiment propre... et je préfère pour le moment la documentation générée par ASDoc par rapport à celle de NaturalDocs (malgré le fait que je préfère la gestion de template de NaturalDocs)

Pour toutes vos questions sur cet article vous pouvez utiliser les commentaires de ce blog mais je vous propose d'aller discuter sur le Google Groups de mon blog.