I'm just in the middle of revisiting maven. Our team had a bad experience when we last looked at this, as it was during the period when maven was rearchitecting from 1.x to 2.x, so a lot of the dependencies we needed hadn't been moved across to the new repositories. However, I have the time to reconsider now.
I am interested in using maven and either LaTeX or DocBook for creating documentation, and I was wondering if anyone had any experiences to share, project/module structure, good plugins to use, etc...
Many thanks :-)
Edit:
Just to clarify, I was looking to write a technical article/book, and my desired artifact would probably be a PDF.
DocBook is one of the many supported inputs to Doxia, the engine used to generate docs by maven. Refer here: http://maven.apache.org/doxia/modules/index.html
In fact, the Doxia site answers your exact question: http://maven.apache.org/doxia/book/index.html
You can easily create a site (that contains documentation) with Maven using the mvn site command (i.e. using the plugin site).
This plugin creates technical reports (such as Javadoc, Unit tests reports, code coverage...) but can be also used to create a "real site".
You have more details about that in this page.
Basically, you write your page using APT (Almost Plain Text which is quite simple to understand), or a XML-based format, Xdoc.
2 years ago, I create a complete user guide for one application I developed, using the XDoc format and the Site Maven plugin. Globally, it was quite easy to create!
I hope this will help you!
I've been using with success the Maven plugin Docbkx. You should give it a try
Docbkx
You should definitely take a look at the Maven Docbkx Plugin. It probably fits your needs. Doxia's support of DocBook is -uhm- suboptimal. In fact, last time I tried it, it generated something new that - as far as I could tell - wasn't DocBook.
The Maven Docbkx Plugin that I'm referring to supports all the customizations of the world (through plugin parameters, or XSLT overrides, if you're into that) + it features some mechanisms to integrate it with the Maven build. (Such as processing instructions for including Maven pom properties into your documents.)
Note that the ambition is to have a plugin that prevents you from having to manually put together a processing chain yourselves. So this plugin will both do the transformation to FO, and transforming that to PDF.
I recently implemented the project documentation for my maven multi-module project using docbook and the docbkx plugin for maven. I now have it automatically generating html and pdf files every time I build the project site. I think docbkx really rocks, so I would suggest you use that.
Its true -you can create a very nice site just using the maven site and doxia plugins. In fact I'm using those two to generate my project site, But doxia support for docbook is very limited and doesn't let you modularize documentation, including parts of documents in a main document, for instance. So for the big reference-manuals I'm using docbkx.
If you want to take a peek, my project is here. You can actually download the source and see the nitty gritty of it. And, of course, if you have any question regarding this setup, i'll be more than glad to help.
Cheers
Carlos
Although the question is quite old I want to give an update on this. If you want to use LaTeX for your documentation you should use a maven plugin to generate the documentation. There are a couple of maven-plugins doing this but a lot of them are not maintained anymore.
There is a new maven-plugin which requires none or less configuration to get it working and the generated PDF (or PS or DVI) can be published as artifact.
Have a look at: mathan-latex-maven-plugin
There is AFAIK no official or semi-official plugin that will process LaTeX or DocBook, but what you could do (besides using the aforementioned site plugin) is to configure the exec plugin to process your LaTeX/DocBook sources during the site lifecycle, i.e. at the same time that the project's website is built.
E.g., something like
<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>
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
We are using Maven for building a Java server-style application. It consists of several modules (in a single Maven "reactor") which can be plugged together to generate a final product (essentially a .jar) with the features enabled that the customer needs. All the internals are documented using JavaDoc and all, but that's not what you can give to the customer to find out how to get the thing running. Currently we have an OpenOffice document which serves as end-user documentation.
I'd like to integrate this documentation into the Maven build process where each module's documentation is maintained (hand-edited) together with the Module's sources and the final document can reference the required Module documentation sections, add some friendly foreword and, if possible at all, can reference into the JavaDocs. Ultimately, the document should be output as a PDF.
Is there any experience on Maven plugins can help with this? Is DocBook the right tool? Maybe Latex? Or something completely different? A sound "stick with OpenOffice and some text blocks" could be an answer, too.
I'm assuming you haven't looked at the Maven site documentation generation yet with the maven-site-plugin. It's pretty robust and will allow you to incorporate and include the JavaDoc generation as well as the content from your OpenOffice document.
While the site documentation doesn't output as a PDF, it does however output as a static HTML website that has lots of capabilities built in. Using Maven profiles, you could configure Maven to generate one site for internal use that includes Surefire test results and other reports for checks like Checkstykle and PMD. In another profile, you could configure it to only generate the documentation necessary for distribution to the clients that doesn't include the internal reports that the clients may not care about.
One note though, much of the site documentation generation is changing for Maven 3. While most of Maven 3 is backwards compatible with Maven 2, be mindful of the reporting changes for Maven 3. Check out these links:
Site Generation Compatibility
Converting maven-site-plugin for
Maven 3
And in case the site plugin with external docs does not produce a high enough quality, you can use docbook with Maven to produce HTML and PDF output. In fact Sonatype does that for all their books (e.g. Maven: The Complete Reference, Nexus book, M2Eclipse book...) and they are open source so you can see how it all works and copy the setup and modify it for your needs. The advantage of using docbook is that the tooling is pretty good (xmlmind for example) and that it produces print quality books with index, toc and so on.
Oh and since you mentioned it there is also a LaTeX plugin for Maven but I have no experience with it (but quite a bit with LaTeX prior to my Maven usage...)
Another solution is the Maven docbkx plugin for conversion of DocBook into PDF; HTML, etc.
Read this description on how to add the converted DocBook to HTML to a Maven project site, if you would like to see your DocBook content also appear in the Maven generated site.
Interesting related questions:
What is the recommended tool chain for formatting XML DocBook?.
I have a multi-module maven project in which each module has it's own reference-manual written in docbook format. And then I have a general reference manual, also written in docbook that includes the others so I am re-using the documentation.
When I execute mvn site, the project generates HTML and PDF files with all the reference manuals and they are neatly integrated into the maven site.
For this I use the docbkx plugin. I think it really rocks. Here is the plugin configuration:
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
<execution>
<id>docbook-HTML</id>
<phase>pre-site</phase>
<goals>
<goal>generate-html</goal>
</goals>
<!-- HTML configuration -->
<configuration>
<generateToc>false</generateToc>
<targetDirectory>${project.build.directory}/site</targetDirectory>
<htmlCustomization>${basedir}/src/site/docbkx-config/docbook-html.xsl</htmlCustomization>
<htmlStylesheet>./css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet>
<chunkedOutput>false</chunkedOutput>
</configuration>
</execution>
<execution>
<id>docbook-PDF</id>
<phase>pre-site</phase>
<goals>
<goal>generate-pdf</goal>
</goals>
<!-- PDF configuration -->
<configuration>
<generateToc>true</generateToc>
<paperType>A4</paperType>
<imgSrcPath>file:///${basedir}/src/site/resources/</imgSrcPath>
<calloutGraphicsPath>file:///${basedir}/src/site/resources/images/callouts/</calloutGraphicsPath>
<calloutGraphicsExtension>.svg</calloutGraphicsExtension>
<calloutGraphicsNumberLimit>30</calloutGraphicsNumberLimit>
<calloutIconSize>6</calloutIconSize>
<shadeVerbatim>true</shadeVerbatim>
<targetDirectory>${project.build.directory}</targetDirectory>
<foCustomization>${basedir}/src/site/docbkx-config/docbook-fo.xsl</foCustomization>
<!-- <bodyFontFamily>Kaffeesatz</bodyFontFamily>
<monospaceFontFamily>LiberationMono</monospaceFontFamily>
-->
<fonts>
<font>
<name>Kaffeesatz</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/YanoneKaffeesatz-Regular.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/YanoneKaffeesatz-Regular-metrics.xml</metricsFile>
</font>
<font>
<name>LiberationMono</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/LiberationMono-Regular.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/LiberationMono-Regular-metrics.xml</metricsFile>
</font>
<font>
<name>VeraMono</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/VeraMono.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/VeraMono-metrics.xml</metricsFile>
</font>
</fonts>
</configuration>
</execution>
</executions>
<!-- Shared configuration -->
<configuration>
<sourceDirectory>${basedir}/src/site/docbkx</sourceDirectory>
<includes>*.xml</includes>
<xincludeSupported>true</xincludeSupported>
<generatedSourceDirectory>${project.build.directory}/site</generatedSourceDirectory>
<highlightSource>1</highlightSource>
<calloutGraphics>true</calloutGraphics>
<!-- DEFAULT HTML CONFIG -->
<targetDirectory>${project.build.directory}/site</targetDirectory>
<htmlCustomization>src/site/docbook-config/docbook-html.xsl</htmlCustomization>
<htmlStylesheet>css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet>
<!-- // DEFAULT HTML CONFIG -->
</configuration>
</plugin>
You can check out my project site here and you can even download the sources into your computer and see how the whole thing is set up.
If you have any questions don't hesitate to reach out.
Hope it helps
Cheers
Carlos
I want to put a configuration file in my Maven project. Looking at the standard directory layout, there are two places that seem sensible, "src/main/resources" and "src/main/config". Could someone explain the difference between these, and explain when you would put something in config and when in resources?
In this case, the file I'm looking at is ehcache.xml, but my question isn't ehcache specific, I'm curious for log4j.properties etc.
A bit of googling discovered this person had the same question, but the answers seemed contradictory, and not very authorative.
The email exchange at http://www.mail-archive.com/users#maven.apache.org/msg90985.html
says:
"This is all theory... Perhaps while writing the docs, someone involved with Maven development thought it might be useful to have a src/main/config directory and so it was included in docs, but since it was never implemented in the code, it is not being used today."
and
"The directory [src/main/config] doesn't show up on the classpath so the application or test classes
can't read anything in it."
So just use src/main/resources.
Note: I don't know if this is true (I'm the question asker), but that would explain why so many people on the web recommend src/main/resources for log4j.properties. If people agree this is the right answer could you let me know (comment or vote) I put it here to save other people the typing.
scr/main/resources is a place where you put your images, sounds, templates, language bundles, textual and binary files used by the source code. All config files like excache.xml, log4j.properties, logback.xml and others go to src/main/config.
Add to your pom.xml:
<build>
<resources>
<resource>
<targetPath>.</targetPath>
<directory>src/main/config</directory>
</resource>
</resources>
</build>
The inclusion of src/main/config in Maven's standard directory layout has been removed due in part to the confusion caused between src/main/config and src/main/resources. This very stackoverflow question is actually referenced in the JIRA ticket for the removal of src/main/config from Maven's standard.
Short answer: Use src/main/resources not src/main/config. It's the (new) Maven way.
Use case is pretty straightforward if you ask me. (It seems src/main/config has since been removed standard directory layout)
/src/main/resources go on into jar and thus on classpath
/src/main/config is intended for assembly plugin where you might construct a
zip file:
hello-world.zip
lib/
<dependencies>
bin/
run.bat
run.sh
config/
config.properies
I'm new to Maven and have skimmed over the documentation as I am following the Hibernate tutorial at http://docs.jboss.org/hibernate/stable/core/reference/en/html_single/#tutorial-firstapp-mvn.
I have installed Maven and successfully setup a web-app but this does not contain all of the standard directories mentioned in the tutorial. Am I going mad?
When building my Maven project I am using the maven-archetype-webapp. This gives me the arh-webapp\src\main\resources and arh-webapp\src\main\webapp directories but I'm missing quite a few directories mentioned on the link http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html.
Surely I don't have to manually add these? If not then the Hibernate documentation does not mention what archetype to use in order to achieve the directory structure used in their tutorial. Please can someone enlighten me.
What archetype do I need to use in order to have the above directory plus the src/main/java directory? If there is no such archetype then can easily append these using Maven? and how?
Surely you'll have to manually add these.
Just create those directories that according to the Maven convention are missing. Remember, a Maven Archetype is just a starting point to save you time configuring your workspace. After encountering many problems in some Archetypes myself I've been accustomed to just use a basic-web-app-archetype and then customize it myself, as a beginner with Maven you'll be better off doing that, and will learn a lot.
Regards.
Not all the directories mentioned are required for your standard web application. In fact, the reason behind the presence of the src/main/java, src/main/resources and the src/main/webapp directories is due to the archetype that you've used.
IMHO, the book titled "Better Builds with Maven" will serve you better; the Sonatype books on Maven might also help. The complete Maven documentation is also available as a PDF file, for future reference.
But just in case, you need some clarity on the terms used, here's some:
Archetype: A pattern for projects. Simple web applications (with no dependencies on other frameworks/libraries) have their own archetypes, so do applications using Spring, Hibernate, Seam, etc. Some archetypes will result in creation of different directories, as they are coded that way. You might be able to change the directory structures in most cases, although I cannot vouch for every archetype. For instance, it is quite possible to place your sources in 'src' instead of 'src/main/java', although this requires additional configuration in the POM.
Lifecycles, Phases and Goals: A Maven build lifecycle is a series of phases, with each phase executing a set of goals. Maven can be commanded to execute a build phase, which results in execution of all phases until and including the specified phase.
Maven plugins: Maven plugins contain one or more goals. Goals need not be bound to phases, but usually you would bind them to particular phases. Plugins are the basis for everything operational in Maven; you're using plugins even though you are just compiling the application (the Maven compiler plugin is a core plugin that is present in the Maven distribution).
I hope the above helps, but I would suggest that the reference books be followed.
Is there an open source project that can serve as a good example on how to use the maven site plugin to generate reports? I would prefer it to
consist of many modules, possibly hierarchically structured
use as many plugins as possible (surefire, jxr, pmd, findbugs, javadoc, checkstyle, you name it)
the reports should be aggregated: if some tests fail you want to have a single page that shows all modules with failing tests, not only a gazillion individual pages to check
include enterprisey stuff (WAR, EAR etc), but this is not so important.
The idea is to have something where you can gather ideas on how it is done and what is possible.
I gave up trying to aggregate reports of a complex multi-modules project with the maven-site-plugin. For this, I use Sonar, it's much more powerful (with features like evolution of metrics over time, aggregation, neat drill down, etc) and just works. Have a look at Nemo, the online demo instance and cry.
For an example see http://www.bartswennenhuis.nl/2013/12/maven-aggregate-reports-for-multi-module-projects/. Findbugs does not support aggregate reports.
I don't think there is such a project, if there is I want to know it as well. In order to find things in maven you have to know what you're looking for(which is not exactly the same with what you want to accomplish).
If its any help I'm building 13 module project with MAVEN, use cobertura maven plugin, surefire, javadoc, etc .. it works as charm, why are you asking this question, you want to determine the capabilities of maven or ?
this is actually a response to your question. please take a look at the Apache Directory project. it contains two big blocks: the directory server and the tooling support (Eclipse based).
you can find the SVN repository of the Apache Directory Studio (this is a complete directory tooling platform intended to be used with any LDAP server) here: http://svn.apache.org/repos/asf/directory/studio/trunk/
take a look at the POM file ( http://svn.apache.org/repos/asf/directory/studio/trunk/pom.xml ) of this multi module project. it consists out of lots of modules, uses most of the plug-ins you're using and it also aggregates some of the reports.this
You can use Violations Maven Plugin to aggregate Findbugs (and many other static code analysis) reports.
It needs to run after the analysis. It will parse their report-files and present them in one unified report. It can, optionally, fail the build depending on number of violations found.
I have to deal with what is pretty ugly and large blob of ColdFusion code which up to this day is maintained by direct modifications on production server (don't ask). I managed to clean it up from dupes and backups and put it into Subversion, now I need tp pick a make system to be able to put this onto continuous build (TeamCity) and also scheduled releases.
To my surprise I only found pretty much a single blog article on how to retrofit CF project with Maven, so the question is - does anyone have experience successfully using Maven on CF and what in general people use to manage large CF projects?
Your suggestions, tips and links will be much appreciated
Since I don't want to start religions wars - Maven is pretty much company standard (vs Ant)
First, here's another blog you might find helpful.
build-tools-maven-and-coldfusion
I haven't tried to build ColdFusion with Maven, but I have experience with managing Maven builds for a large company. There are a few things for you to consider.
Project structure
Coldfusion cfm and cfc files should be put in src/main/resources so they are bundled in the jar (the blog referenced above overrides the Maven convention to put them in src. this is ok, but could be a problem if you later need to add anything else to the project).
I'd probably keep cfc and cfm files in separate projects with appropriate dependency declarations to link them, this keeps your cfc projects as libraries and helps reuse. It is also worth considering the granularity of the cfc projects. Generally Maven's dependency management helps you keep artifacts small, with little need to worry about finding all the jars.
Deployment
The simplest way to deliver the artifacts is to use the maven-war-plugin to create a war containing your artifacts and all their transitive dependencies. This makes each application self-contained, which can be useful. The downside of this is that you'll end up bundling the same artifacts repeatedly and they can be quite large. To mitigate this you can either use the assembly-plugin to create custom packages excluding the common components, or you can specify that certain components (e.g. ColdSpring) are scope provided, this means they won't be included in the war.
Version Management
Maven encourages a proliferation of dependencies, by default each dependency declaration has a version, this can cause maintenance issues, particularly when you want to bump the version of an external dependency. You can mitigate this by defining a parent POM or an "app" POM. Either would have a dependencyManagement section declaring the details (groupId, artifactId, and version) for common artifacts. Any POM inheriting from the parent need not declare the dependency version as it will be inherited (note this doesn't mean that all children will have all dependencies, only that any that declare a dependency don't need to declare the version). If you define an "app" project with packaging "pom" and a dependencyManagement section, you can reference it with scope import (from Maven 2.0.9 onwards), this will import the dependencyManagement section from the "app" project to the project POM. See the dependency documentation for more details.
If you declare a dependency with a scope in the dependencyManagement section, that scope will be inherited unless it is overridden in the child POM. Related to the deployment section above, this means that you can declare the common libraries scope provided in the parent to ensure they are not bundled in each applciation.
Naming Conventions
You'll need a naming convention for the packages to avoid collisions.
It's probably best to follow the Maven convention and use java package-like groupIds (org.apache.maven for maven.apache.org) and the jar name for the artifact. This convention would give the groupId "org.coldspringframework" and artifactId "coldspring" for ColdSpring.
Further distinctions might need to be made across the company. For example, if you have a web and core team, you could give the web team the groupIds com.mycompany.web.* and the core team com.mycompany.core.*
Dependency Management
You'll need to add your CFC packages to a Maven repository such as Nexus so they are accessible to other builds across the enterprise.
If you want to keep the CFC packages separate to the jars. You can specify a custom packaging type, so that they won't be mixed up with any Java artifacts. If you create a custom packaging type, the artifacts can have the ".jar" extension, but any dependency declaration must have the type set.
Here's an example following those conventions:
<dependency>
<groupId>org.coldspringframework</groupId>
<artifactId>coldspring</artifactId>
<version>1.2</version>
<!--custom packaging type helps keep separate from Java artifacts-->
<type>cfc</type>
</dependency>
There's a section in the Nexus book that describes custom lifecycles (follow the links for more details. Essentially you need to create a plugin with a META-INf/plexus/components.xml to describe the plexus mechanics (what archiver to use, what extension to output etc).
The components.xml would look something like this:
<component-set>
<components>
<component>
<role>org.apache.maven.lifecycle.mapping.LifecycleMapping</role>
<role-hint>cfc</role-hint>
<implementation>org.apache.maven.lifecycle.mapping.DefaultLifecycleMapping</implementation>
<configuration>
<phases>
<process-resources>org.apache.maven.plugins:maven-resources-plugin:resources</process-resources>
<package>com.hsbc.maven.plugins:maven-jar-plugin:jar</package>
<install>org.apache.maven.plugins:maven-install-plugin:install</install>
<deploy>org.apache.maven.plugins:maven-deploy-plugin:deploy</deploy>
</phases>
</configuration>
</component>
<component>
<role>org.apache.maven.artifact.handler.ArtifactHandler</role>
<role-hint>cfc</role-hint>
<implementation>org.apache.maven.artifact.handler.DefaultArtifactHandler</implementation>
<configuration>
<extension>jar</extension>
<type>cfc</type>
<packaging>cfc</packaging>
</configuration>
</component>
<component>
<role>org.codehaus.plexus.archiver.Archiver</role>
<role-hint>cfc</role-hint>
<implementation>org.codehaus.plexus.archiver.zip.ZipArchiver</implementation>
<instantiation-strategy>per-lookup</instantiation-strategy>
</component>
<component>
<role>org.codehaus.plexus.archiver.UnArchiver</role>
<role-hint>cfc</role-hint>
<implementation>org.codehaus.plexus.archiver.zip.ZipUnArchiver</implementation>
<instantiation-strategy>per-lookup</instantiation-strategy>
</component>
</components>
</component-set>
Maven looked interesting to me too, but I couldn't find enough resources, and didn't have enough time to figure it out, so I moved onto what seemed to be good as well.
I understand you prefer to use Maven, I have come across several articles regarding Ant and Coldfusion, as well as a recent one about Hudson with Coldfusion.
Coldfusion also has the cfant (undocumented) tag. You can run ANT scripts right from CF?