Docbook a été très connu en fait. Il était énormément utilisé fut un temps. Je me rappelle même avoir fait quelques XSL simplifiées vers 2003 (ah ce petit plaisir coupable d'écrire du XSL...).
Il est relativement passé de mode maintenant, notamment à cause de son aspect verbeux qui le rend un peu pénible à écrire et assez pénible aussi à relire. Le temps de génération est aussi assez lourd comparé à l'outil dont je vais parler juste après.
Pour la documentation Hibernate, on est passé à AsciiDoctor (http://asciidoctor.org/) depuis quelques années pour la rédaction des documentations. On convertissait toujours la documentation en Docbook après pour avoir la sortie PDF, AsciiDoctor ne la proposant pas à l'époque. J'ai revisité le sujet récemment et AsciiDoctor a maintenant une chouette version PDF.
Pour les prochaines versions, on s'oriente donc maintenant vers une pure sortie AsciiDoctor (je vais pousser une nouvelle version d'Hibernate Validator dans l'aprèm avec le nouveau format de doc, je posterai des liens avant après).
La capacité à inclure facilement des bouts de code est vraiment chouette aussi. Il est également possible de relativement facilement ajouter des balisages complémentaires.
C'est en Ruby mais AsciiDoctor propose également un plugin Maven qui fonctionne par dessus JRuby. C'est ce dernier que nous utilisons.
Dans les moins par rapport à ce dont tu parlais, la sortie epub est encore assez perfectible pour des documentations du calibre de ce qu'on a. On a décidé de ne pas la publier pour l'instant.
# Aaaah Docbook...
Posté par Guillaume Smet (site web personnel) . En réponse au journal DocBook ou l'art d'écrire de la documentation. Évalué à 8.
Docbook a été très connu en fait. Il était énormément utilisé fut un temps. Je me rappelle même avoir fait quelques XSL simplifiées vers 2003 (ah ce petit plaisir coupable d'écrire du XSL...).
Il est relativement passé de mode maintenant, notamment à cause de son aspect verbeux qui le rend un peu pénible à écrire et assez pénible aussi à relire. Le temps de génération est aussi assez lourd comparé à l'outil dont je vais parler juste après.
Pour la documentation Hibernate, on est passé à AsciiDoctor (http://asciidoctor.org/) depuis quelques années pour la rédaction des documentations. On convertissait toujours la documentation en Docbook après pour avoir la sortie PDF, AsciiDoctor ne la proposant pas à l'époque. J'ai revisité le sujet récemment et AsciiDoctor a maintenant une chouette version PDF.
Pour les prochaines versions, on s'oriente donc maintenant vers une pure sortie AsciiDoctor (je vais pousser une nouvelle version d'Hibernate Validator dans l'aprèm avec le nouveau format de doc, je posterai des liens avant après).
Un exemple de bout de doc :
- version rendue par GitHub (c'est aussi un des avantages) : https://github.com/hibernate/hibernate-validator/blob/master/documentation/src/main/asciidoc/ch02.asciidoc
- version code : https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch02.asciidoc
La capacité à inclure facilement des bouts de code est vraiment chouette aussi. Il est également possible de relativement facilement ajouter des balisages complémentaires.
C'est en Ruby mais AsciiDoctor propose également un plugin Maven qui fonctionne par dessus JRuby. C'est ce dernier que nous utilisons.
Dans les moins par rapport à ce dont tu parlais, la sortie epub est encore assez perfectible pour des documentations du calibre de ce qu'on a. On a décidé de ne pas la publier pour l'instant.
Je conseille chaudement.