Documenter son code frontend

Bonjour bonjour.

Suite à un nouveau boulot (yey) où je vais m'incruster dans une équipe, reprendre et créer de nouveaux projets, j'ai cherché pour une solution qui me permette de créer une doc de mon code (frontend) histoire de faciliter le travail pour mes collègues quand ils auront à reprendre mon code, l'utiliser de leur côté ou autre...

Et là stupeur, incapable de trouver de solution qui colle à mon workflow, qui génère des docs correct avec résultat + markup + code css...

Du coup je me suis mis en tête de coder le mien. Pour le moment j'ai une version fonctionnelle très basique (basée sur node.js) qui fonctionne à peu prés, mais j'aurai aimé avoir vos retour sur les fonctionnalités qui pourraient éventuellement vous intéresser si vous faîtes déjà des docs pour la partie frontend de vos projets, ou si vous comptiez en faire.

Pour l'utilisation, à l'heure actuelle ça se passe comme ça :

dans le terminal, je me déplace jusqu'à mon dossier, je tape "node docs.js css/global.css" et ensuite à chaque fois que j'édite ce fichier css, il le lit, et génère la page, qui contient, dans des commentaire des titres de modules, descriptions et des exemples de markups, qui sont ensuite affichés tous ensemble dans une page _doc.html .

Dans ma to-do list, j'ai déjà :

- faire une page plus jolie (dans le style de http://ricostacruz.com/backbone-patterns/ par exemple )
- utiliser un formatting proche de javadoc
- utiliser markdown pour les descriptions/commentaires, pour une magnifique mise en forme
- re-coder le tout parce que pour le moment c'est du système D

J'attends vos suggestions, et je continue de travailler là dessus pour avoir quelque chose à vous montrer bientôt

Je n'ai malheureusement pas de solution pour toi,

Mais le site que tu citais en exemple (http://ricostacruz.com/backbone-patterns/) est effectivement très bien fait !!

Oui, dans le même genre il y a aussi http://jashkenas.github.com/docco/ qui est pas mal.

Ils sont tous les deux pour du backend, mais au moins y'a l'idée de commentaire + code, reste plus qu'à ajouter le visuel et le tour est joué... ou presque. Je suis déjà en train de bosser sur la partie design, en attendant que des solutions me tombent dessus pour le code.

Nan la coloration syntaxique c'est assez simple, y'a plein de trucs pour ça.

L'idée c'est de générer/coder un document, qui contiendra tous les éléments utilisé sur un site (composants UI) de façon visuel, avec le code HTML et CSS associé.

L'objectif c'est de cumuler un guide de styles (à quoi sert tel élément, et dans quel circonstances l'utiliser), générer du même coup de la doc pour le css et le html pour s'y retrouver facilement derrière (donc comme de la doc pour des libs Java, sauf que c'est du Html et Css à la place.

D'un point de vue processus de travail, je trouve ça intéressant de s'attaquer aux éléments chacun de leur côté, pour ensuite les mélanger, ça aide à structurer le code, séparer tout dans des fichiers biens à leur place, qui s'occupent de leur tambouille et pas du reste, et la page peut servir de checklist quand on modifie quelque chose pour vérifier que ça a rien cassé dans les autres éléments.

Ensuite pour le côté travail en équipe, au lieu d'avoir à me demander quel est le markup souhaité pour tel "widget" ou autre, suffit de regarder la doc (ou l'exemple qui est dans le code css) pour voir ce à quoi ça doit ressembler, et comment c'est supposé être en plus de notes éventuelles sur les choix niveau code, design ou autre.

Et pour finir, ça peut faire partie des délivrables qu'on fourni à un client, déjà parce que je trouve que ça fait super classe de fournir de la doc (raison compte double), ensuite parce que si c'est quelqu'un d'autre qui prend en charge la suite du projet, ça leur donne la possibilité de comprendre les choix faits, et de poursuivre dans la même direction, etc etc.

Donc je trouve qu'en soit ça peut être un outil intéressant à plusieurs niveaux, le seul soucis, c'est que pour un résultat correct... j'ai rien trouvé qui colle à mon workflow, qui prenne pas des heures, et qui soit potable. Y'avait bien cssdoc, mais c'est mort depuis 2009, et ça a pas l'air d'avoir été finalisé. Sinon y'a d'autres solutions à base de gems et d'app indépendantes rails mais bon... Je préfère encore un seul fichier, qui requiert node en local et qui n'est que du html une fois généré.


Pour résumer :
* Quand tu fais ton intégration, dans ton css tu as des commentaires, qui contiennent des notes et/ou exemples de markup
* N'importe quand tu peux générer la doc à partir de ta feuille de style
* Tu peux passer la doc à ton client, tes collègues, la garder pour plus tard, la partager
* Si quelqu'un reprend ton boulot, y'a plus de chances qu'ils comprennent pourquoi tu as fait comme ci ou comme ça et qu'ils poursuivent dans la même direction (qui, soyons optimiste, est la bonne)

Sinon, je cherche plus trop, j'ai déjà cherché et je n'ai rien trouvé, donc à la place je me suis mis en tête de le faire moi même. Si y'a des gens dans le coin qui serait intéressés par un tel outil, ils ont peut être des idées, donc je demandes, si certains produisent déjà ce genre de documents, le genre de fonctionnalités dont ils se servent, comment ils formattent leur code, comment ils s'organisent, ou autre, tous les retours ou suggestions sont bons à prendre.
Modifié par HammHetfield (18 Feb 2012 - 17:16)