Fix :spring-authorization-server-docs:asciidoctor cacheability

[jprinet]

Issues

• The task is relying on inputs with absolute paths and therefore not getting cache hits when the cache is relocated.

• The whole docs/src/docs/asciidoc folder is silently passed as an input to the task and this modifies the inputs depending on test task being fetched from build cache or not:

Fix

This PR:

• converts entries from the attributes Map with absolute paths to relative paths (docs-java requires an absolute path and has to be moved into an asciidoc internal file attributes.adoc)
• add an exclusion on AsciiDocTask resources

[sjohnr]

Thanks @jprinet, appreciate the effort here!

• The task is relying on inputs with absolute paths and therefore not getting cache hits when the cache is relocated.
• The whole docs/src/docs/asciidoc folder is silently passed as an input to the task and this modifies the inputs depending on test task being fetched from build cache or not:

I'm not able to find information about this cache miss in a previous successful build (possibly due to unfamiliarity with Gradle Enterprise). Are you able to link to where you see the cache miss called out in the build?

This PR:

• converts entries from the attributes Map with absolute paths to relative paths (docs-java requires an absolute path and has to be moved into an asciidoc internal file attributes.adoc)

The challenge I had with getting the docs set up originally was being able to edit docs locally in my IDE (with adoc file preview) while also having asciidoctor happy with all of the paths for resolution during a build. Asciidoctor picks a magical relative root for all paths to be resolved that the IDE has no idea about, which is quite frustrating.

The issue I'm finding with this change is that it breaks the relative pathing set up for preview. I'm also not entirely sure what it fixes. Can you explain why this change was necessary? I may not be fully understanding the need.

• add an exclusion on AsciiDocTask resources

It seems like this is the real issue with cache misses, correct? Could we just relocate the examples folder to be outside the src/docs/asciidoc directory? Or is there something else that makes this necessary?

[jprinet]

I'm not able to find information about this cache miss in a previous successful build (possibly due to unfamiliarity with Gradle Enterprise). Are you able to link to where you see the cache miss called out in the build?

A cache miss due to inputs relying on absolute paths happens when relocating your cache, you can demonstrate it by running experiment 3 of the automated validation scripts.
The experience is about running 2 builds with the project cloned from 2 different locations on an empty cache. You will then get the following cache miss on the second build:

Please note that the PR also solves these deprecation warnings, as Gradle happens to identify some implicit dependencies between tasks likely due to this.

The challenge I had with getting the docs set up originally was being able to edit docs locally in my IDE (with adoc file preview) while also having asciidoctor happy with all of the paths for resolution during a build. Asciidoctor picks a magical relative root for all paths to be resolved that the IDE has no idea about, which is quite frustrating.

Not sure how to make the change compliant with your use case. Would keeping the examples-dir variable definition in the guides help there?

It seems like this is the real issue with cache misses, correct? Could we just relocate the examples folder to be outside the src/docs/asciidoc directory? Or is there something else that makes this necessary?

That is a part of the problem but wouldn't be sufficient afaik

[jprinet]

Which IDE / plugin are you using @sjohnr?
I have tried to reproduce locally with IntelliJ and the default AsciiDoc plugin, but both default and PR branch are leading to an exception.

[jprinet]

I eventually found a way to make the plugin work in my environment, I also pushed a new commit which overrides the attributes in the subfolder.
Could you give it a try @sjohnr ?

[sjohnr]

Yes, I'm using AsciiDoc plugin. I tried your new branch and that indeed seems to take care of it! I'm not sure why I was having trouble, as it seems straightforward now. Thanks so much!

On a related note, I'm only partially able to verify the cache miss issue with Gradle Enterprise builds. I tried the automated validation scripts but I seem to lack permissions on Gradle Enterprise to get any value out of it. I could potentially ask for more permissions, perhaps I'll do that at a later time. In the meantime, I think I'll revert the changes for the experiment for now.

Either way, I think I have enough info to incorporate this contribution, which I'll work on later this week. Thanks again!

[jprinet]

That's a good news, although I'm not super happy that an extra guides/attributes.adoc file is required only to make the IDE plugin happy.

With regards to the automated experiments, my understanding is that you are missing READ API permissions from Gradle Enterprise. This prevents the scripts from automatically fetching the experiment results.
You could ask for more permissions or investigate the experiment results by yourself by just checking that no cacheable task actually run in the second build. To do so, just filter the second build scan of the experiment like there.

[sjohnr]

That's a good news, although I'm not super happy that an extra guides/attributes.adoc file is required only to make the IDE plugin happy.

I set up the guides to be a subdirectory of the documentation site, which doesn't seem to be intended by asciidoctor, so it's likely my fault. I think this is only temporary as we will eventually switch to Antora which has a more well-defined project structure and a default location for examples. I believe it has its own IDE plugin as well.

[sjohnr]

Thanks @jprinet! This is now merged to main as 2f7c4f6.