docs zip does not contain reference html files (5.7.3)

[fgunbin]

Describe the bug
README.adoc says that "./gradlew build" will build docs, but it builds only api docs. I could not find a way to build reference locally.

To Reproduce
./gradlew build

Expected behavior
docs/build/distributions/spring-security-5.7.3-docs.zip contains reference htmls

[sjohnr]

Thanks for pointing this out, @fgunbin!

We're currently working on the docs. See this comment. Currently, you can run ./gradlew :spring-security-docs:antora to get a local build of the reference.

I believe the reference docs have not been built using the ./gradlew build command since we switched to Antora. Just to confirm, you aren't reporting an issue where this recently changed, correct?

I'll leave this open and we can decide whether we want the build task to build the reference, or if we want to update the readme to state that building the reference is a separate task (since it could take some time to include an npm build every time).

[fgunbin]

@sjohnr Thanks for your reply,

Yes, I think this changed with the switch to Antora.
Building reference with separate task seems to be ok, so perhaps only readme should be updated.

BTW, I had this error when running antora task:
error: configuration param 'antora.extensions' not declared in the schema
I had to comment out antora.extensions in docs/antora-playbook.yml to get the build success (but a bit broken docs, I suppose). Does anyone else observe this, or it's something in my environment? What additional info should I provide?

[marcusdacoregio]

@fgunbin I think this error that you mentioned occurs if you are executing the command on a branch different than main. For now, we are limited to execute the antora commands only on the main branch.

[fgunbin]

@marcusdacoregio
Hm, on main branch the project builds successfully (with JDK 17), but
./gradlew :spring-security-docs:antora
gives this:

> Task :spring-security-docs:generateAntora FAILED

FAILURE: Build failed with an exception.

* Where:
Build file '/Users/fgunbin/src/spring-security/docs/spring-security-docs.gradle' line: 82

* What went wrong:
Execution failed for task ':spring-security-docs:generateAntora'.
> Failed to calculate the value of task ':spring-security-docs:compileTestJava' property 'javaCompiler'.
   > class org.apache.xerces.parsers.XIncludeAwareParserConfiguration cannot be cast to class org.apache.xerces.xni.parser.XMLParserConfiguration (org.apache.xerces.parsers.XIncludeAwareParserConfiguration is in unnamed module of loader org.gradle.internal.classloader.VisitableURLClassLoader @465a9c51; org.apache.xerces.xni.parser.XMLParserConfiguration is in unnamed module of loader org.gradle.initialization.MixInLegacyTypesClassLoader @4ef37659)

[sjohnr]

Sorry @fgunbin I'm not able to reproduce that error, and ./gradlew :spring-security-docs:antora works fine on main.

$ java -version
openjdk version "17.0.4" 2022-07-19
OpenJDK Runtime Environment Temurin-17.0.4+8 (build 17.0.4+8)
OpenJDK 64-Bit Server VM Temurin-17.0.4+8 (build 17.0.4+8, mixed mode, sharing)

What Java version/distribution are you using?

[fgunbin]

@sjohnr

I'm using OpenJDK 17.0.4.1, built myself:

openjdk version "17.0.4.1-internal" 2022-08-12
OpenJDK Runtime Environment (build 17.0.4.1-internal+0-adhoc.fgunbin.jdk-17.0.4.1)
OpenJDK 64-Bit Server VM (build 17.0.4.1-internal+0-adhoc.fgunbin.jdk-17.0.4.1, mixed mode, sharing)

This JDK is not installed system-wide, I'm invoking Gradle with JAVA_HOME, like this:

JAVA_HOME=~/software/java17/jdk ./gradlew -v

------------------------------------------------------------
Gradle 7.4.2
------------------------------------------------------------

Build time:   2022-03-31 15:25:29 UTC
Revision:     540473b8118064efcc264694cbcaa4b677f61041

Kotlin:       1.5.31
Groovy:       3.0.9
Ant:          Apache Ant(TM) version 1.10.11 compiled on July 10 2021
JVM:          17.0.4.1-internal (Oracle Corporation 17.0.4.1-internal+0-adhoc.fgunbin.jdk-17.0.4.1)
OS:           Mac OS X 11.6.1 x86_64

I will now build & try 17.0.4.

[fgunbin]

@sjohnr The same with self-built 17.0.4. I've also tried 17.0.2 binaries from openjdk.org (https://jdk.java.net/archive/), the same error.

[sjohnr]

Bummer, sorry @fgunbin. I'm not familiar with what could be causing that error in this case.