spring-restdocs-asciidoctor is incompatible with AsciidoctorJ 1.6 and later #581
Comments
|
Ouch. Thanks for the report. I wonder how much in common the root cause of this and the root cause of spring-io/spring-asciidoctor-extensions#9 have in common? I'll see what I can do. Hopefully it'll be possible to be compatible with the two versions. I really don't want to have to have Maven- and Gradle-specific variants of the |
|
I guess the main problem here is actually the Maven asciidoctor plugin, which still uses 1.5.8. If it used 1.6.x as the gradle plugin does, a new version of Spring-REST-Docs could just depend on 1.6.x for everything. |
|
I can work around the binary incompatibilities of @Override
public void register(Asciidoctor asciidoctor) {
try {
Object javaExtensionRegistry = asciidoctor.getClass()
.getMethod("javaExtensionRegistry").invoke(asciidoctor);
javaExtensionRegistry.getClass().getMethod("preprocessor", Preprocessor.class)
.invoke(javaExtensionRegistry, new DefaultAttributesPreprocessor());
Object rubyExtensionRegistry = asciidoctor.getClass()
.getMethod("rubyExtensionRegistry").invoke(asciidoctor);
rubyExtensionRegistry.getClass().getMethod("loadClass", InputStream.class)
.invoke(rubyExtensionRegistry, RestDocsExtensionRegistry.class
.getResourceAsStream("/extensions/operation_block_macro.rb"));
rubyExtensionRegistry.getClass()
.getMethod("blockMacro", String.class, String.class)
.invoke(rubyExtensionRegistry, "operation", "OperationBlockMacro");
}
catch (Exception ex) {
throw new IllegalStateException("Failed to register Asciidoctor extensions",
ex);
}
}This moves things along, but a failure then occurs because the signature of In AsciidoctorJ 1.6, it is now the following: I can't implement those two methods in the same class, or even in the same module. This leaves me with a few choices:
I don't really like any of these, but I like 3 the least. It requires users to be aware of the differences and to figure out the right module to use. It's particularly bad as moving to a new patch release of Asciidoctor's Gradle plugin would require moving to a different variant of the |
|
I've opened asciidoctor/asciidoctor-maven-plugin#385 to explore the possibility of the Maven plugin aligning its AsciidoctorJ dependency with that of the Gradle plugin. |
|
asciidoctor-maven-plugin 1.6.0 (using AsciidoctorJ 1.6.2) has been released. However, this is a temporal fix. Given AsciidoctorJ is still in Release candidate cycle, so maybe rest-docs v2.0.4 should hold to 1.6.x and start a 2.1.0 pointing to AsciidoctorJ 2.x, once a stable release is available? |
|
@wilkinsona @abelsromero think about the spring restdocs 1.x users too that need a migration path to asciidoc 1.6 then 2.x but also a migration path to spring boot 2.x as well. |
|
Any update on this ? |
|
Not yet, no. I've yet to have the time to figure out exactly what the right approach is going to be. Ideally, a maintenance release of REST Docs could add support for new versions of AsciidoctorJ but all the ways of achieving that [that I've thought of thus far] are pretty unpleasant. An alternative would be a new minor release of REST Docs that requires AsciidoctorJ 1.6, but with AsciidoctorJ 2.0 approaching, that's only going to be a short-term solution. |
|
Yes, indeed, thanks @wilkinsona for the insight in this issue ! |
|
I have the same problem, use Exception log: I noticed that the version of asciidoctorj 2.0 has been officially released. |
|
Even though I am not a user of spring-restdocs, I am willing to help to get this resolved if someone of the Spring side can collaborate with me on this. |
|
Thanks very much, @ysb33r. I'd love to collaborate on a solution. As it stands, the problem is caused by my desire for Spring REST Docs' Asciidoctor extensions to support AsciidoctorJ 1.5.x (as they have always done) and 1.6.x at the same time, and the breaking changes made in AsciidoctorJ 1.6.x. The nature of the breaking changes is such that a reflection-based solution will not work. Without any compatibility improvements in AsciidoctorJ, that leaves a few options as listed above:
Another option would be a new minor release of REST Docs that raises the minimum supported version of AsciidoctorJ to 1.6, but there aren't enough other new features to warrant such a release at the moment. Of the other three options, I still dislike 3 the most. I'm probably leaning towards 2 as the complexity is then dealt with at build time rather than at runtime. I still strongly prefer a solution at the AsciidoctorJ level so that this can be solved for the whole ecosystem in a single, central location. |
|
If I understand it correctly the real problem itself is the AciidoctorJ API changes and not the actual Gradle plugin. Is that a correct assumption? |
|
Yes, that's right. REST Docs doesn't interact at all with the Gradle (or Maven) plugin. The API incompatibility is in AsciidoctorJ. That said, the Gradle Plugin did exacerbate the problem by upgrading to AsciidoctorJ 1.6 in a 1.5.x plugin release. |
Would a Kotlin DSL warrant such a release? I have one waiting to be reviewed ;-) |
If people use 1.5.11 or 1.5.12 of the Gradle plugin, they will not have this problem as that puts AsciidoctorJ 1.5 back as the default version. Now for the longer term, you would probably want to look to upgrade everything to rather have all extensions compile against AsciidoctorJ 2.0 instead. Due to this, I would suggest not working with Asciidoctor Gradle 2.0, but rather look at being prepared for when Asciidoctor Gradle 3.0 is released as it supports AsciidoctorJ 2.0. (Asciidoctor Gradle 2.0 can use AsciidoctorJ 2.0, but only if no additional GEMs are specified). We areadly have two releases of Asciidoctor Gradle 3.0 in alpha, and the next version should go out this week of 17 June 2019. If you would consider creating an integration branch that could be Asciidoctor 2.x compatible, I could definitely help to iron out integration issues. |
|
As to the problem potentially also being excerbated by the Maven plugin, I am not sure where the state of that is yet, but I know @abelsromero is working towards getting a Maven plugin out which is AsciidoctorJ 2.0 compatible. |
|
The released 2.0.0-RC.1 maven plugin is already compatible with AsciidoctorJ 2.0.0. To "For all intents and purposes"the plugin has moved on to 2.0.0 (which is the final version for 1.6.x). In my opinion, while it's nice and desirable to support all AsciidoctorJ versions, the documentation format itself is compatible. From a user stand point the only requirement to upgrade will be updating the pom configurations and maybe some custom extension. The third-party extensions listed in the README will need some work too, but they will be faced with the same dilemma here at some point. |
Thanks, I hadn't noticed they'd reverted to 1.5 by default. That simplifies things quite a bit as it avoids the problem that @jnizet originally reported above. |
It would if we had the Java counterpart to go with it. I've still not found the time that I need to work on that unfortunately. |
The problem is that users won't all upgrade at the same pace. This is less likely at the moment now that the 1.5.x Gradle plugin has dropped back to AsciidoctorJ 1.5, but will become a bigger problem again in the future. I am sure that some users will want to be able to use the new major version of the Asciidoctor build plugins with REST Docs while others will want to stick with the current versions of the build plugins as they're working fine for them. This leaves REST Docs either having to support two version of AsciidoctorJ at the same time, or having a new minor (or even major) release of REST Docs that requires the new major release of AsciidoctorJ and the associated build plugins. |
|
@wilkinsona The READMEs on Asciidoctor Gradle for the various versions (1.5.x, 1.6.x, 2.x and 3.x) now contain notes w.r.t. to spring-restdocs compatibility. Basically it boils down to people should remain using 1.5.11 or 1.5.12 if they use spring-restdocs. Once the latter is upgraded to support AsciidoctorJ 2.0 (not 1.6) they will be able to use the 3.x range of asciidoctor-gradle. (In a similar note asciidoctor-maven 2.x). Just to clarify the versioning on Asciidoctor Gradle:
|
wilkinsona
changed the title
|
I've bitten the bullet and split things out into several modules so that I can compile against AsciidoctorJ 1.5, 1.6 and 2.0 and deal with their various incompatibles. The existing |
|
This should hopefully now be fixed in the latest 2.0.4 snapshot available from https://repo.spring.io/libs-snapshot. If anyone affected by the incompatibilities has a chance to give it a try and provide some feedback, that would be much appreciated. |
|
Here's my feedback on the 2.0.4 snapshot release (I tested it with gradle 5.1). I started by setting the version of the spring-restdocs-mockmvc and spring-restdocs-asciidoctor dependencies to 2.0.4.BUILD-SNAPSHOT.
So, @wilkinsona, everything works fine with the snapshot 👍 , with all the tested versions of the asciidoctor plugin, even though using the latest version needs adaptations (and thus changes to the spring-restdocs documentation) Fixing the error is easy: the asciidoctor task must be modified to explicitly add the projectdir attribute: Before: After: I tried running with @ysb33r fixing the warning message to use the correct command line option would be nice. So I tried using the plugin "org.asciidoctor.jvm.convert" instead of "org.asciidoctor.convert". This plugin doesn't create the
After: Also note that the generated html file is now located under |
|
Thanks very much, @jnizet. The need to create the
|
@jzinet That has been fixed, but not released yet. |
|
@jzinet Also see asciidoctor/asciidoctor-gradle-plugin#404 regarding your Kotlin DSL discoveries. |
Using the latest version (1.5.10) of the gradle plugin
org.asciidoctor.convertcauses the following exception to be thrown:Using the previous version (1.5.9.2) works fine.
It would be a good idea I guess to release a new version of spring-restdocs that is built against the newest stable version of AsciidoctorJ (the gradle plugin currently uses AsciidoctorJ version 1.6.1, and the latest version is 1.6.2). Unfortunately, the Maven plugin still uses AsciidoctorJ version 1.5.8. Not sure if it's possible to be compatible with the two versions.
The text was updated successfully, but these errors were encountered: