Creazione di documentazione con Maven

Question

Sono nel bel mezzo di una rivisitazione di Maven. La nostra squadra ha avuto una brutta esperienza quando l'abbiamo guardato per l'ultima volta, come è stato durante il periodo in cui Maven stava eseguendo la ricerca da 1.xa 2.x, quindi molte delle dipendenze di cui avevamo bisogno non erano state trasferite nei nuovi repository . Tuttavia, ho il tempo di riconsiderare adesso.

Sono interessato all'utilizzo di Maven e LaTeX o DocBook per la creazione di documentazione e mi chiedevo se qualcuno avesse qualche esperienza da condividere, struttura del progetto / modulo, buoni plugin da usare, ecc ...

Mille grazie :-)

Modifica:

Giusto per chiarire, stavo cercando di scrivere un articolo / libro tecnico e il mio artefatto desiderato sarebbe probabilmente un PDF.

Answer 1

Di recente ho implementato la documentazione del progetto per il mio progetto multi-modulo di maven usando docbook e il plugin docbkx per maven. Ora ho automaticamente generare file HTML e PDF ogni volta che costruisco il sito del progetto. Penso che docbkx sia davvero formidabile, quindi suggerirei di usarlo.

È vero, puoi creare un sito molto carino semplicemente usando il sito maven e i plugin doxia. In effetti sto usando quei due per generare il sito del mio progetto, ma il supporto di doxia per docbook è molto limitato e non consente di modulare la documentazione, incluse parti di documenti in un documento principale, ad esempio. Quindi per i grandi manuali di riferimento sto usando docbkx.

Se vuoi dare un'occhiata, il mio progetto è qui . Puoi effettivamente scaricare la fonte e vederne la nitidezza. E, naturalmente, se hai qualche domanda su questa configurazione, sarò più che felice di aiutarti.

Saluti Carlos

Answer 2

DocBook è uno dei tanti input supportati su Doxia, il motore utilizzato per generare documenti da Maven. Fare riferimento qui: http://maven.apache.org/doxia/modules/index.html

In effetti, il sito Doxia risponde alla tua domanda esatta: http: //maven.apache .org / Doxia / libro / index.html

Answer 3

Puoi facilmente creare un sito (che contiene documentazione) con Maven usando il comando mvn site (cioè usando il sito del plug-in ).

Questo plugin crea rapporti tecnici (come Javadoc, rapporti sui test unitari, copertura del codice ...) ma può anche essere usato per creare un "sito reale". Hai maggiori dettagli a riguardo in questa pagina .

Fondamentalmente, scrivi la tua pagina usando APT ( Quasi testo normale che è abbastanza semplice da capire), o un formato basato su XML, Xdoc .

2 anni fa, ho creato una guida per l'utente completa per un'applicazione che ho sviluppato, utilizzando il formato XDoc e il plug-in Site Maven. A livello globale, è stato abbastanza facile da creare!

Spero che questo ti possa aiutare!

Answer 4

Ho usato con successo il plug-in Maven Docbkx. Dovresti provarlo

Docbkx

Answer 5

Dovresti assolutamente dare un'occhiata al Maven Docbkx Plugin . Probabilmente si adatta alle tue esigenze. Il supporto di Doxia per DocBook è -uhm- non ottimale. In effetti, l'ultima volta che l'ho provato, ha generato qualcosa di nuovo che - per quanto ho potuto dire - non era DocBook.

Il plugin Maven Docbkx a cui mi riferisco supporta tutte le personalizzazioni del mondo (attraverso i parametri del plug-in o le sostituzioni XSLT, se ci sei dentro) + presenta alcuni meccanismi per integrarlo con la build di Maven. (Ad esempio istruzioni di elaborazione per l'inclusione delle proprietà di Maven pom nei tuoi documenti.)

Nota che l'ambizione è di avere un plugin che ti impedisce di dover mettere insieme manualmente una catena di elaborazione. Quindi questo plugin farà sia la trasformazione in FO, sia la trasformazione in PDF.

Answer 6

Anche se la domanda è piuttosto vecchia, voglio dare un aggiornamento su questo. Se si desidera utilizzare LaTeX per la documentazione, è necessario utilizzare un plugin maven per generare la documentazione. Ci sono un paio di plugin maven che lo fanno, ma molti di loro non vengono più mantenuti.  Esiste un nuovo plug-in Maven che non richiede nessuna o meno configurazione per farlo funzionare e il PDF generato (o PS o DVI) può essere pubblicato come artefatto.

Dai un'occhiata a mathan-latex-maven-plugin

Answer 7

Non esiste AFAIK nessun plug-in ufficiale o semi-ufficiale che elaborerà LaTeX o DocBook, ma ciò che potresti fare (oltre a utilizzare il suddetto plug-in del sito) è configurare il plug-in exec per elaborare le tue fonti LaTeX / DocBook durante il ciclo di vita del sito , vale a dire contemporaneamente alla creazione del sito Web del progetto.

Ad esempio, qualcosa del genere

<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>