Use javadoc-extension #1914
Use javadoc-extension #1914
Conversation
Signed-off-by: Tran Ngoc Nhan <ngocnhan.tran1996@gmail.com>
spring-projects-issues
added
the
status: waiting-for-triage
Signed-off-by: Tran Ngoc Nhan <ngocnhan.tran1996@gmail.com>
jgrandja
added
type: enhancement
There was a problem hiding this comment.
Thanks for the PR @ngocnhan-tran1996. Please see review comments.
| "spring-authorization-server-version": project.version | ||
| 'spring-authorization-server-version': project.version, | ||
| 'spring-security-reference-base-url': "https://docs.spring.io/spring-security/reference/${generateVersionWithoutPatch(springSecurityVersion)}".toString(), | ||
| 'javadoc-location-org-springframework-security': "https://docs.spring.io/spring-security/site/docs/$springSecurityVersion/api".toString(), |
There was a problem hiding this comment.
I'm not sure if this is correct?
I reviewed the changes in Spring Security spring-security#15386 and the gradle task syncAntoraAttachments was added which copies the javadoc as an asset to the site. I'm wondering if we need to do the same here?
@rwinch Is there a way to copy the Spring Security javadoc as an asset to the Spring Authorization Server site docs and reference it via a site asset? Or is this correct by directly referencing the Spring Security javadoc site?
There was a problem hiding this comment.
@rwinch As a side note, it appears syncAntoraAttachments is a required gradle task otherwise the antora build will fail saying it cannot find the javadoc resource. For example, after adding javadoc:org.springframework.security.oauth2.server.authorization.OAuth2AuthorizationCode[], the build will fail unless I add the syncAntoraAttachments task. However, this is not documented in Javadoc, unless I'm missing something?
There was a problem hiding this comment.
If we have the way copy the Spring Security javadoc to to the Spring Authorization Server, please let me know
There was a problem hiding this comment.
@rwinch Is there a way to copy the Spring Security javadoc as an asset to the Spring Authorization Server site docs and reference it via a site asset?
You should copy Spring Authorization Servers javadoc to the Antora site, but you should NOT copy Spring Security's Javadoc.
The javadoc extension is just syntactic sugar for creating a link to Javadoc and can operate in a numerous different ways. It creates a link and does NOT create/copy Javadoc in the location it is pointing to.
Linking to Spring Authorization Server Javadoc
The default mode is to use xref:attachment$api/java which, as an xref to an attachment, will be validated by Antora that the link exists. This means you can get validation of the javadoc links existing for free. You will use this mode for linking to Spring Authorization Server javadoc. Since the javadoc extension is just creating a link, you still need to ensure that the Javadoc is added.
Spring Security configures the Antora Collector Extension to invoke the generateAntoraResources task (and in turn generateAntoraYml and syncAntoraAttachments). The generateAntoraYml task is how dynamic properties like version are set properly and synAntoraAttachments is how the Javadoc is generated/added as attachments to the site. Once it is added to the site, the Javadoc is automatically published as a part of your site.
Linking to Other Module's Javadoc
As for linking to other module's Javadoc (e.g. Spring Security), you should NOT copy it. Instead use Package Specific Locations or Link Specific Locations. You will notice that these demonstrate ways that external sites can be linked to. In this case it is more obvious, but worth pointing out that the javadoc extension does not publish the javadocs. It is just syntactic sugar for creating a link to something that must already exist.
The main points:
javadoc:org.springframework.security...instead{spring-security-api-base-url}...