While writing the release notes for Spring Boot 2.3.0.M2, I've realized that the structure of the reference doc for the Maven and Gradle plugins are almost identical but not quite.
Now that we use the same infrastructure for both guides, I wonder if there wouldn't be an interest to also harmonize the structure.
The reference doc of Gradle is at https://docs.spring.io/spring-boot/docs/2.3.0.M1/gradle-plugin/reference/html/
The reference doc of Maven is one level down (no reference): https://docs.spring.io/spring-boot/docs/2.3.0.M1/maven-plugin/html/
I don't know if an end goal would be to share the same anchor but if we did, changing the name of the plugin would point to the relevant doc.
Example for the new build image feature:
- Gradle: https://docs.spring.io/spring-boot/docs/2.3.x-SNAPSHOT/gradle-plugin/reference/html/#build-image Maven: https://docs.spring.io/spring-boot/docs/2.3.x-SNAPSHOT/maven-plugin/html/#build-image
Comment From: scottfrederick
+1 for making this consistent. I've tried to switch between the docs by just replacing gradle with maven in the URL, or the reverse, and been surprised when that didn't work (not necessarily at the level of anchors, but at least at the root).
Comment From: wilkinsona
One area where the two plugins differ is that the Gradle plugin has both API documentation and reference documentation whereas the Maven plugin only has reference documentation. Unless we add reference/ to the Maven documentation’s directory structure purely for consistency, the two won’t be able to match up.
Taking a step back, I’m not sure what the benefit of matching up would be. I imagine that most users will be using either Maven or Gradle and switching between one of the other will be an unusual thing to do.
While there are similarities in structure and content at the moment, I think we should be wary of constraining ourselves too much in the future. Whatever we decide to do here, I think it’s important to leave ourselves room for the documentation to evolve. We need to be able to meet the needs of Maven and Gradle users independent of the other build system.
Comment From: rajeshkumarwf
If issue is still valid,then may i work on this?
Comment From: snicoll
@rajeshkumarwf thanks for offering to help. This issue is opened, with a milestone and isn't assigned yet. As such, someone can work on it. Are you willing to do that?
Comment From: rajeshkumarwf
@snicoll thanks for your reply. Yes, I would like to work on this issue.
Comment From: snicoll
alright, the issue is yours, thanks!
We'd need the javadoc to be generated so that the distribution zip contains an api directory with the javadoc. The current reference doc should move from the root of that zip to a reference directory. This would give a consistent structure with the Gradle plugin, i.e. https://docs.spring.io/spring-boot/docs/2.3.0.M2/gradle-plugin/
Comment From: snicoll
@rajeshkumarwf it's been a while. Are you still willing to work on this issue? Thanks!
Comment From: rajeshkumarwf
Hey @snicoll , I am not keeping well since weeks. Sorry,i am not sure when i will be back to work
Comment From: wilkinsona
No problem, @rajeshkumarwf. Thank you for letting us know and I hope you get well soon.
Comment From: codebuster007
Hi! @snicoll , I can see you've assigned this to yourself. If this is still valid and you'll want some help, I'll like to work on this issue.
Also could you please point me to where the javadocs generation is done.
Thanks.
Comment From: snicoll
Thanks for the offer @codebuster007 but I am done.