Création de documentation avec maven

StackOverflow https://stackoverflow.com/questions/264951

Question

Je suis juste en train de revisiter Maven. Notre équipe a eu une mauvaise expérience la dernière fois que nous avons examiné cette question, comme ce fut le cas pendant la période où Maven procédait à une nouvelle architecture de 1.x à 2.x, de sorte que bon nombre des dépendances dont nous avions besoin n'avaient pas été déplacées vers les nouveaux référentiels. . Cependant, j'ai le temps de reconsidérer maintenant.

Je suis intéressé par l’utilisation de maven et de LaTeX ou de DocBook pour la création de documentation. Je me demandais si quelqu'un avait une expérience à partager, une structure de projet / module, de bons plug-ins à utiliser, etc.

Merci beaucoup: -)

Modifier:

Juste pour préciser, je cherchais à écrire un article / livre technique et mon artefact souhaité serait probablement un PDF.

Était-ce utile?

La solution

J'ai récemment implémenté la documentation de projet pour mon projet multi-module maven à l'aide de docbook et du plug-in docbkx pour maven. Je l’ai maintenant en train de générer automatiquement des fichiers html et pdf à chaque fois que je construis le site du projet. Je pense que docbkx est vraiment génial, je vous suggère donc de l'utiliser.

C'est vrai, vous pouvez créer un très beau site en utilisant simplement le site maven et les plugins doxia. En fait, j'utilise ces deux technologies pour générer mon site de projet. Toutefois, la prise en charge de docbook par doxia est très limitée et ne vous permet pas de modulariser la documentation, y compris des parties de documents dans un document principal, par exemple. Donc, pour les gros manuels de référence que j'utilise docbkx.

Si vous souhaitez jeter un coup d'œil, mon projet est ici . Vous pouvez réellement télécharger la source et en voir le détail. Et, bien sûr, si vous avez des questions concernant cette configuration, je serai ravi de vous aider.

A bientôt Carlos

Autres conseils

DocBook est l’une des nombreuses entrées prises en charge dans Doxia, le moteur utilisé pour générer des documents par maven. Reportez-vous ici: http://maven.apache.org/doxia/modules/index.html

En fait, le site Doxia répond à votre question: http: //maven.apache .org / doxia / book / index.html

Vous pouvez facilement créer un site (contenant de la documentation) avec Maven à l'aide de la commande mvn site (c'est-à-dire à l'aide de la commande site du plugin ).

Ce plugin crée des rapports techniques (tels que Javadoc, des rapports de tests unitaires, la couverture de code, etc.), mais peut également être utilisé pour créer un "site réel". Vous avez plus de détails à ce sujet dans cette page .

En gros, vous écrivez votre page à l'aide de APT ( Presque texte simple qui est assez simple à comprendre), ou un format basé sur XML, Xdoc .

Il y a 2 ans, j'ai créé un guide de l'utilisateur complet pour une application que j'ai développée, en utilisant le format XDoc et le plugin Site Maven. Globalement, c'était assez facile à créer!

J'espère que cela vous aidera!

J'utilise avec succès le plugin Maven Docbkx. Vous devriez faire un essai

Docbkx

Vous devez absolument consulter le plug-in Maven Docbkx . Cela correspond probablement à vos besoins. Le support de DocBook par Doxia est -uhm- suboptimal. En fait, la dernière fois que j'ai essayé, cela a généré quelque chose de nouveau qui - pour autant que je sache - n'était pas DocBook.

Le plug-in Maven Docbkx auquel je fais référence prend en charge toutes les personnalisations du monde (via les paramètres de plug-in, ou les substitutions XSLT, si vous y êtes) +, il dispose de mécanismes pour l'intégrer à la construction Maven. (Telles que les instructions de traitement pour inclure les propriétés de pom Maven dans vos documents.)

Notez que l’ambition est de disposer d’un plug-in qui vous évitera d’avoir à créer manuellement une chaîne de traitement. Donc, ce plugin fera à la fois la transformation en FO et la transformation en PDF.

Bien que la question soit assez ancienne, je souhaite faire le point à ce sujet. Si vous souhaitez utiliser LaTeX pour votre documentation, vous devez utiliser un plugin maven pour générer la documentation. Plusieurs plugins maven le font mais beaucoup d’entre eux ne sont plus maintenus.  Il existe un nouveau plug-in maven qui nécessite une configuration minimale ou minimale pour le faire fonctionner et le PDF généré (ou PS ou DVI) peut être publié en tant qu'artéfact.

Consultez: avec mathan-latex-maven-plugin

AFAIK ne dispose d’aucun plug-in officiel ou semi-officiel qui traitera LaTeX ou DocBook, mais vous pouvez le faire (en plus de l’utilisation du plugin de site susmentionné), c’est configurer le plugin exec pour traiter vos sources LaTeX / DocBook pendant le cycle de vie du site. C'est-à-dire en même temps que le site web du projet est construit.

exemple, quelque chose comme 

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <executions>
    <execution>
    <id>latex</id>
    <goals>
      <goal>exec</goal>
    </goals>
    <phase>site</phase>
      <configuration>
          ...
      </configuration>
    </execution>
  </executions>
</plugin>
Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top