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

[Erik Joelsson]

On Wed, 16 Oct 2024 16:19:51 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 TEST_DEPS when calling tests using test-$1
>   
>   drop docs/req.flg

make/RunTests.gmk line 877:

> 875:     DOCS_PATH := $$(OUTPUTDIR)/images/docs
> 876:   endif
> 877:   $1_JTREG_BASIC_OPTIONS += -e:DOCS_IMAGE_DIR=$$(DOCS_PATH)

Looking at this again, I just realized we do have this path defined in spec.gmk already, but with a different name: `DOCS_JDK_IMAGE_DIR` (along with `DOCS_JAVASE_IMAGE_DIR` and `DOCS_REFERENCE_IMAGE_DIR`). I think we should stick with this existing name instead of introducing a new one, so it's consistent across the whole build system. Then we don't need this fallback to $(OUTPUTDIR) anymore. `DOCS_JDK_IMAGE_DIR` will either be defined in spec.gmk from configure or from jib-profiles when running `run-tests-prebuilt-docs`.

make/conf/jib-profiles.js line 1007:

> 1005: 
> 1006:     testOnlyProfilesPrebuiltDocs["run-test-prebuilt-docs"].dependencies.push("docs.doc_api_spec", "tidy");
> 1007:     testOnlyProfilesPrebuiltDocs["run-test-prebuilt-docs"].environment["DOCS_IMAGE_DIR"] = input.get("docs.doc_api_spec", "install_path");

Change to DOCS_JDK_IMAGE_DIR.

test/docs/tools/tester/DocTester.java line 34:

> 32:  */
> 33: public class DocTester {
> 34:     private final static String DIR = System.getenv("DOCS_IMAGE_DIR");

Change to DOCS_JDK_IMAGE_DIR.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21272#discussion_r1803543004
PR Review Comment: https://git.openjdk.org/jdk/pull/21272#discussion_r1803544554
PR Review Comment: https://git.openjdk.org/jdk/pull/21272#discussion_r1803545527