Add sbt-paradox docs

[mdedetrich]

About this change - What it does

This PR adds documentation using sbt-paradox

Resolves: #50 , #28 , #19

Why this way

The PR does quite a few changes many of which is already documented in the docs which this PR providers. Here are some additional notes

• The documentation in some areas of Guardian had to be fixed/updated otherwise document generation fails when using scaladoc
• Due to issues with paradox the oldest JDK version that Guardian now supports is Java 11. This is because -XX:+IgnoreUnrecognizedVMOptions doesn't work fully in JDK 8 and using -XX:+IgnoreUnrecognizedVMOptions is the only way to make sbt-paradox work with multiple JDK versions
• Although initial support for sbt-paradox-project-info was included, its currently not being used because I am waiting for a release which fixes the following issue Make levels optional lightbend/sbt-paradox-project-info#18 (comment)
• Changes to sbt-github-actions was done to firstly check that the documentation compiles on every PR and to also publish the documentation when a PR has been merged to master.

[coveralls]

Pull Request Test Coverage Report for Build 1962932619

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 76.676%

---

Totals
Change from base Build 1962928117:	0.0%
Covered Lines:	263
Relevant Lines:	343

---

💛 - Coveralls

[reta]

why do you need -XX:+IgnoreUnrecognizedVMOptions?

[mdedetrich]

In that file some options only apply to specific versions of JVM and by default if you pass an option into the JVM that doesn't exist it will immediately terminate. --illegal-access=permit only works on JVM 16 and --add-opens java.base/java.lang=ALL-UNNAMED only works on JVM 17

[reta]

May be we could do better?

• provide a runnable script which properly assemble command line options
• adopt https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#jvm-options-syntax

Why I am concerned: we should not silence invalid JVM command line options / flags, the users should be aware of any mismatches here.

[mdedetrich]

I thought of this originally but the issue here is the typical way/s that SBT is used. For example a lot of people (myself included) use Intellij's SBT integration when working with Scala projects. When using sbt like this the only possible way to pass JVM arguments is with .jvmopts since Intellij behind the scenes uses the sbt directly via a jar for its integration. The same applies to the official sbt launcher script which is included when you install sbt via your operating systems package manager (homebrew, apt, pacman etc etc).

Ideally sbt should have support for dynamically supporting different JVM options depending the JVM option but this doesn't exist yet. Note the complication here is that the JVM args are designed for the build tool, not the runtime of the project that gets compiled. Its trivial for SBT to support different JVM arguments when you run tests/programs compiled by SBT (sbt supports forking the JVM with different JVM args when running tests) but in this case the JVM arguments are actually needed for the build tool itself (the document generation is done via a SBT plugin)

[reta]

👍 all set!