I'm looking for possibilities for generating documentation using DocBook as part of my Maven build process. What I'm finding is everyone is suggesting docbkx-maven-plugin over Doxia. The problem is that it seems docbkx is no longer maintained or at least they've moved and left no forwarding address for where to look at the source code. According to the plugin's website the repository is on googlecode.com which of course hasn't existed for many years now. The last update I found of the plugin was back in 2016. This leads me to believe that the plugin is no longer maintained. Does anyone have any news to the contrary, or a different option for generating DocBook output during a maven build?
The source is available here: https://github.com/mimil/docbkx-tools
It does look like the project is no longer maintained, having seen no commits since 2015.
You don't actually need the plugin. If you have a working DocBook toolchain, you can use Maven to invoke it. The plugin could make certain aspects easier, but it also adds a limitation in that it only supports HTML output.
Related
Can a custom Maven plugin use incremental build support from core Maven or would it best have to implement that completely itself, with SHA1 hashes over the input and the like?
Noticed e.g. /target/maven-status/maven-compiler-plugin/compile/default-compile with createdFiles.lst and inputFiles.lst, so thinking that an existing custom e.g. code generator Maven plugin, which reads some files as input, generates some output, may be able to be changed to correctly use Maven Plugin APIs for incremental build? Unclear what specifically that plugin code would have to do differently than it does today for it to become incremental. Doesn't look like there is any doc about this?
Existing code does use e.g. org.sonatype.plexus.build.incremental.BuildContext.hasDelta(File), but with "return true" in org.sonatype.plexus.build.incremental.DefaultBuildContext.hasDelta(File) it's not surprising that this doesn't quite work... ;-) Is this not implemented in Maven, or can be configured differently? Would this require the takari-lifecycle-plugin? (That would be a problem in the case of the particular plugin I'm asking for, because the use of takari-jar instead of normal JAR would interfere with other plugins.)
Understood that the custom Maven plugin likely would have to interface with Maven core API to expose its notion of dependencies between the input files. In the case of this particular custom Maven plugin, some of the input is read from dependencies on the project's classpath. Would the incremental support be able to handle that as well?
Understood that existing Maven plugins, such as maven-compiler-plugin, are struggling with incremental builds (à la Gradle); see [1], [2] and [3], so this Q is specifically to learn about how a custom Maven plugin may be extended to support incremental build.
[1] http://takari.io/2014/10/16/incremental-compilation.html
[2] http://takari.io/book/40-lifecycle.html
[3] Does Maven support incremental builds?
can Maven custom plugins use incremental build support from core Maven?
yes. take a look on the sources of 'querydsl-maven-plugin'. also you can find more usages of BuildContext.hasDelta method with grepcode.com.
does it have to implement that itself?
may it? yes. have to? no.
usually such question means just an unnecessary preemptive optimization. you have to have a rational reason to look forward on incremental builds, before you start implement anything.
I found this note in the Maven's documentation:
You can add elements to this classloader by extensions. These are loaded into the same place as ${maven.home}/lib and hence are available to the Maven core and all plugins for the current project and subsequent projects (in future, we plan to remove it from subsequent projects).
I couldn't understand what they mean by "subsequent projects" here. As far as I understand, extensions are enhancements to lifecycle phases of Maven and are not project specific. So it makes sense to work for all the Maven projects.
Question: Can anyone explain what this statement means "in future, we plan to remove it from subsequent projects"
First an extensions can be extensions of a life cycle but not need to. You can implement an extensions also as an EventSpy for example.
This documentation is related to the Core Classloader which is available within such extensions and makes it also possible to enhance it via an extensions. This classloader contains those files from ${maven.home}/lib which is not a good idea and not necessary. It would be better having only the Maven Plugin API there and it's instances which are currently used and not more...
There existing some extensions like Wagon which are using to make a transport in special cases possible which could be project specific.
Starting with Maven 3.3.1 the core extensions mechanism has been improved to make loading project specific extensions more simpler which means they are located into ${maven.projectBasedir}/.mvn/extensions.xml file and also being loading from an repository. Before 3.3.1 you need to do that manually via mvn -Dmaven.ext.class.path=extension.jar.
Is there a plugin in gradle which can generate maven site similar thing? It would be great if it was compatible with current maven site apt format file.
It seems that there are two plugins, this and this. The first one was committed four years ago, I know nothing about the second. So it seems that these plugins will not be helpful.
I just wrote one as part of Gradle Fury. The primary plugin(s) (it's really just a collection of scripts) for Gradle-Fury is to enhance/fix many of the gradle short comings on publishing, android stuff, pom stuff, etc. Since there's pretty much no standard way for most things in gradle, we jam most of those configurations in the gradle.properties file. That said, the site plugin does depend on those settings to correctly stylize the site.
In short, to apply to your project...
put this in your root build.gradle file
apply from 'https://raw.githubusercontent.com/gradle-fury/gradle-fury/master/gradle/site.gradle'
Next edit your gradle.properties file and use this link as a template for your pom settings....
https://github.com/gradle-fury/gradle-fury/blob/master/gradle.properties
Create a src/site/ directory.
Make a src/site/index.md file as your home page
Copy/clone following files/folders from https://github.com/gradle-fury/gradle-fury/tree/master/src/site
css
images
img
js
template.html
Finally, build the site with gradlew site. Default output is to rootDir/build/site
Don't like the way it looks? (it looks like the Apache Fluido theme from the maven site plugin). Just edit template.html to meet your needs.
I'm currently working on a mechanism to bootstrap the site plugin which will remove a few of these steps, but that's what it is right now. More info and complete feature list is at the wiki
One last note, should run gradlew site after all of your check tasks, but it's not wired up to depend on it. Basically, anything that produces reports for your modules should be ran before site since it's aggregated into the site package, including javadocs and much more. The rest of the fury scripts help automate much of the painful configuration steps. Worth checking out (see the quality and maven-support plugins)
Disclaimer: I'm one of the authors.
Edit: site preview: http://gradle-fury.github.io/gradle-fury/
Edit: We just cut an updated version that makes manual creation of src/site and all the copy/clone tasks from the master repo unnecessary. Just run gradlew site while internet connected and it'll do the rest for you.
We check all of our source code's dependent third-party JARs into source control along with our source code. When needed, we manually download updates to third party JARs and replace those JARs that are in source control with the newer versions. We haven't felt the need to use Maven yet as this process seems simple enough for us. But are we missing something of great value by not using Maven? Or does our scenario not warrant using Maven?
"JARs dont change much", I hear this all the time.....
Storing jars in the SCM is simple in the beginning of the project. Over time the number of jars gets larger and larger.... Wait 2 or 3 years and nobody remembers where the jars came from, what their licensing terms were and most commonly what versions are being used (important to know when analysing security vulnerabilities).....
The best article I've read recently making the case for a repository manager is:
http://www.sonatype.com/people/2012/07/wait-you-dont-have-a-repository-manager/
A little irreverant, but does make a valid point about the kind of technical inertia one encounters all the time.
Switching a project team from ANT to Maven can be scary.... Maven works quite differently, so I find it is best deployed with greenfield or adventurous project teams. For the old-school ANT users, I recommend using the Apache ivy plugin. Ivy allows such teams to outsource the management of their dependencies but keep the build technology they're comfortable with.
Ultimately the biggest benefit of using Maven are not dependency management. It's the standized build process. I've seen several failed attempts to create a "standard" ANT build process. Problem every build engineer has his opinion on what the standard should be.... Maven's approach of forcing users to write build plugins may appear restrictive in the beginning, but just like the iPhone eventually developers discover "there's a Maven plugin for that" :-)
When it comes to dependency management Maven really can be quite valuable. As Mark O'Connor suggests, running a local repository manager would likely be better than checking the artifacts into source control.
There are many tools (like m2e in eclipse) that can help with dependency management and provide valuable feedback on which modules or dependencies require which other dependencies. Maven will also make sure to get the appropriate version of a dependency even if different modules depend on different versions of a given library. That will help prevent duplicate versions of the same jar showing up in your deployed project as long as they have the same group and artifact id.
Even for a very simple project I don't think I would resort to checking dependencies into the source control system.
It's not only about 3rd Party Libraries. Mostly if you have multiple repositories. In our case, we had four repositories with lots of inter- and intra-dependencies.
Actually I started this answer and then I had to go for 15 minutes to talk to some colleague about a problem happened after someone forgot to update the .jar of one project in the other's lib directory.
And it looks more professional :)
What happened to the Maven Polyglot project that used to be at http://polyglot.sonatype.org/?
As described in this article,
One exciting new feature in Maven 3 is it's ability to work with pom files written in non-XML notations. The Maven core now provides an underlying DSL to access the Maven internals, and write POM files in the language of your choice. This currently includes scripting languages like Groovy, Ruby, and others. In short, you will be able to write a DSL for virtually any scripting language you like that can hook into the Maven internals and pilot the Maven build process.
There are several additional articles on the web that I've found referencing the feature.
http://www.thinkplexx.com/learn/article/maven-learn-material/maven3/maven3-pom-using-groovy-ruby-scala-yaml-sonatype-polyglot
http://mattgivney.blogspot.com/2011/05/maven-3-polyglot-support.html
But the polyglot site now redirects to sonatype.org and I can find no mention of this feature in the Maven 3 release notes.
So what happened? Was it cut or is it in there and just not documented in the release notes? If it did make the cut for Maven 3 could you point to some documentation. I am also interested in the translator tool mentioned by the first article I linked to.
This project is now named tesla-polyglot. I've just completed the Scala DSL for it, and tesla-polyglot should be released very soon now. We're just waiting on Maven 3.1.1 to roll out of the door.
There has been an update on the maven users list from Jason van Zyl: http://maven.40175.n5.nabble.com/What-happened-to-Polyglot-Maven-td5715529.html
I'm still working on it along with a few others. Dhanji has the Atom markup working, Kristian has implemented a Ruby DSL, and Jason Dillon has implemented a Groovy DSL which creates synthetic plugins to bind arbitrary scripting to Maven's lifecycle. My original was to see how Maven's infrastructure could be leveraged by other markups and DSLs. These examples do render to an interoperable format insofar as consumers go. Maven itself obviously cannot run a Ruby DSL but if you like the Ruby DSL you can use it to build an not affect consumers: you can build and deploy to a Maven repository and someone else can consume the dependency with stock Maven.
I have all the early adopters I can deal with one-on-one right now, because I can't deal with many really, but if you have more than a passing interest feel free to email me privately.
looks like it is still alive :-)
You won't believe it, but it's released (if you can call a 0.1 version a release).
As of April 2016,
the home page is https://github.com/takari/polyglot-maven ,
the latest release is 0.1.15
There is Polyglot Maven IDE Pack for Eclipse, that includes some plugins.
There is also maven-tiles project https://github.com/repaint-io/maven-tiles ,
and quick trying out what Maven flavor works well shows that Groovy does better than others.
Be aware of Babylon Tower problem, so it is actually better when most of developers use the same flavor.
The latest info comes from here
"Polyglot for Maven is still moving along and we've seen a lot of activity recently on the Ruby DSL by Cristian Meier from the JRuby team, and the Scala DSL by Chris Hunt from Typesafe. We hope that this initial work can serve as inspiration for helping the POM evolve. For those interested in what the XML alternatives can look like you can take a look at the existing implementations:
Ruby DSL
Groovy DSL
Scala DSL
YAML
Atom"