Erstellen von Dokumentation mit Maven

Question

Ich bin gerade in der Mitte der Maven Revisiting. Unser Team hatte eine schlechte Erfahrung, als wir uns das zuletzt angesehen haben, wie es in der Zeit war, als Maven von 1.x auf 2.x rearchitecte, also waren viele Abhängigkeiten, die wir brauchten, nicht in die neuen Repositories verschoben worden . Allerdings habe ich jetzt die Zeit, es zu überdenken.

Ich bin an mit Maven und entweder LaTeX oder DocBook-Dokumentation für das Erstellen, und ich habe mich gefragt, ob jemand irgendwelche Erfahrungen teilen musste, Projekt-/Modulstruktur, gute Plugins zu verwenden, etc ...

Viele dank :-)

Edit:

Nur um zu klären, ich war auf der Suche einen Fachartikel/Buch und mein gewünschter Artefakt wahrscheinlich ein PDF wäre zu schreiben.

Answer 1

Ich habe kürzlich die Projektdokumentation für mein Maven-Multimodul-Projekt mit Docbook und dem docbkx-Plugin für Maven implementiert. Ich habe es jetzt automatisch generieren HTML-und PDF-Dateien jedes Mal, wenn ich die Projektseite erstellen. Ich denke docbkx rockt wirklich, also würde ich vorschlagen, dass Sie das verwenden.

Seine wahre - Sie können eine sehr schöne Seite nur mit der Maven-Site und Doxia Plugins erstellen. Tatsächlich verwende ich diese beiden, um meine Projektwebsite zu generieren. Aber die doxia-Unterstützung für docbook ist sehr begrenzt und erlaubt es Ihnen nicht, die Dokumentation zu modularisieren, zum Beispiel Teile von Dokumenten in einem Hauptdokument. Für die großen Referenzhandbücher verwende ich docbkx.

Wenn Sie einen Blick werfen möchten, ist mein Projekt here. Sie können die Quelle tatsächlich herunterladen und sehen, wie wichtig es ist. Und wenn Sie Fragen zu diesem Setup haben, werde ich Ihnen gerne weiterhelfen.

Prost Carlos

Answer 2

Sie können mit Maven mithilfe des Befehls mvn site (d. H. Mit der plugin site) ganz einfach eine Site erstellen (die Dokumentation enthält).

Dieses Plugin erstellt technische Berichte (wie Javadoc, Unit Tests Berichte, Code Coverage ...), kann aber auch verwendet werden, um eine "echte Website" zu erstellen. Sie haben mehr Details dazu in this page.

Grundsätzlich schreiben Sie Ihre Seite mit APT (Fast Plain Text, die ganz einfach zu verstehen) oder ein XML-basiertes Format, Xdoc.

Vor 2 Jahren habe ich ein vollständiges Benutzerhandbuch für eine von mir entwickelte Anwendung erstellt, die das XDoc-Format und das Site Maven-Plugin verwendet. Weltweit war es ziemlich einfach zu erstellen!

Ich hoffe, das wird Ihnen helfen!

Answer 3

Es gibt kein offizielles oder halboffizielles Plugin, das LaTeX oder DocBook verarbeitet, aber Sie können das exec Plugin verwenden, um Ihre LaTeX/DocBook Quellen während der Site zu bearbeiten Lebenszyklus, dh zur gleichen Zeit, zu der die Website des Projekts erstellt wird.

Z. B. so etwas wie

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

Answer 4

DocBook ist eine der vielen unterstützten Eingänge doxia, den Motor zur Erzeugung von docs maven verwendet. Siehe hier: http://maven.apache.org/doxia/modules/index.html

In der Tat, die doxia Website Ihre genaue Frage beantwortet: http://maven.apache.org/doxia/book/index.html

Answer 5

Ich habe das Maven Plugin Docbkx mit Erfolg verwendet worden. Sie sollten es versuchen

Docbkx

Answer 6

Sie auf jeden Fall einen Blick auf die Maven Docbkx Plugin nehmen sollte. Es entspricht wahrscheinlich Ihren Bedürfnissen. Doxias Unterstützung von DocBook ist -uhm- suboptimal. Beim letzten Mal, als ich es ausprobierte, erzeugte es etwas Neues, das, soweit ich es beurteilen konnte, nicht DocBook war.

Das Maven Docbkx Plugin, auf das ich mich beziehe, unterstützt alle Anpassungen der Welt (durch Plugin-Parameter oder XSLT-Overrides, wenn Sie das wollen) + es verfügt über einige Mechanismen, um es mit dem Maven Build zu integrieren. (Wie zum Beispiel Verarbeitungsanweisungen für die Aufnahme von Maven Pom Eigenschaften in Ihre Dokumente.)

Beachten Sie, dass das Ziel ist, ein Plugin zu haben, das Sie daran hindert, manuell eine Verarbeitungskette zusammenzustellen. Dieses Plugin wird also sowohl die Transformation zu FO als auch die Umwandlung in PDF durchführen.

Answer 7

Obwohl die Frage ziemlich alt ist, ich will auf dieses Update geben. Wenn Sie LaTeX für Ihre Dokumentation verwenden möchten, sollten Sie ein Maven-Plugin verwenden, um die Dokumentation zu erstellen. Es gibt ein paar Maven-Plugins, die das tun, aber viele von ihnen werden nicht mehr gepflegt. Es gibt ein neues maven-plugin, das keine oder weniger Konfiguration benötigt, damit es funktioniert und das generierte PDF (oder PS oder DVI) als Artefakt veröffentlicht werden kann.

Werfen Sie einen Blick auf: mathan-latex-maven-plugin