RFR: 8340818: Add a new jtreg test root to test the generated documentation [v5]

[Magnus Ihse Bursie]

On Fri, 11 Oct 2024 12:54:42 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this change that adds a new test root `docs` dedicated to testing the documentation, which has been a work in progress for a while. Tests for links, encoding, HTML, accessibility will be later added in following PRs. 
>> 
>> We also define a new make target `test-docs` meant for local use and depends on the docs.
>> This also adds the necessary configurations needed at Oracle.
>> 
>> This patch includes a test `TestDocs` which serves to show developers how they are meant to resolve the docs to test them, I want to include it temporarily until better tests are added later.
>> 
>> TIA
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add tidy as a dependency to `run-test-prebuilt-docs` and `docs` profiles

I'm wondering a bit on how the new `test-docs` target works with the pre-existing pattern of `test-<test>`, for the test names that we detect in FindTests.gmk. If anyone would add a jtreg group named `docs`, things would be very weird. 

Right now there is a `docs_all` group, which mean that you can run `make test-docs_all`. But this will not automatically bring in the dependency on the docs, and so will fail unless this has already been run.

It seems that the intention here is that you should always use `make test-docs TEST=docs_all` to run the tests in the new `docs` root.

I'm not sure if this is the best, or even the right, way to do this.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/21272#issuecomment-2407637067