RFR: JDK-8176785 Add build support to generate PNG file from .dot file

[Magnus Ihse Bursie]

On 2017-04-11 16:03, Magnus Ihse Bursie wrote:
> Here is an updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.04/ 
>
>
> This change does not stop requiring the full exploded image to be 
> built first when building full docs. However, full-docs will no longer 
> be automatically enabled, even when all prerequisites are present, so 
> for normal uses (where the user does not give --enable-full-docs), 
> this dependency will not be present.
>
> The problem here is that if we do that, we will end up with broken 
> Javadoc in the image/docs directory, since the generated HTML will 
> contain an "<img src="$m-graph.png"..>" tag, but the png file itself 
> will not exist. During an offline discussion, this was deemed acceptable.

Obviously, miscommunication can arise even outside this mailing list. 
:-) I misunderstood Erik. Here's yet another (hopefully final) version 
of the patch, which does split the generation in two separate steps. 
This change introduces target names which will hopefully make it harder 
to accidentally build broken documentation, even though it will be 
possible if you try really hard. :)

The idea behind the new name schema is that the docs image after JEP 299 
will end up with two directories, "api" and "specs", and we'll have a 
docs image for jdk (the "normal" docs image) and a special image 
containing the Java SE documentation only, to serve as reference for the 
Java SE specification ("javase-docs").

So we get docs-jdk and docs-javase for the two respective top-level 
targets. Then we break them down in docs-jdk-api and docs-jdk-specs 
(will be created in a separate change). And finally, docs-jdk-api 
consists of docs-jdk-api-javadocs and, if running with full docs, 
docs-jdk-api-modulegraph. Running any of the two latter targets 
individually will result in a non-consistent api directory, but running 
any of docs-jdk-api or docs-jdk will ensure it's consistent.

http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.05

/Magnus

> I have changed the names of the targets to be more clear. Now we have 
> "docs-jdk" and "docs-javase" as the "top level" javadoc targets. For 
> these, we (currently) have the sub-targets "docs-jdk-javadoc" and 
> "docs-javase-javadoc", but as part of JEP 299, more will soon follow. 
> I have kept "docs-javadoc" as a legacy alias for "docs-jdk-javadoc".
>
> I have also incorporated the fixes from Mandy's comment.
>
> /Magnus
>
>
> On 2017-04-07 13:02, Erik Joelsson wrote:
>> Hello,
>>
>> This looks good in general. One thing I don't like about this is that 
>> if full docs is enabled, the docs-javadoc target now requires the 
>> full exploded image to be built first. I think that's unfortunate. 
>> Would it be possible to introduce separate targets for the gengraphs 
>> parts so that the main javadoc call can be run independently of most 
>> of the rest of the build, using the existing docs-javadoc target (and 
>> the newer docs-reference, even though I think that name is bit 
>> strange in this context)?
>>
>> /Erik
>>
>>
>> On 2017-04-07 10:40, Magnus Ihse Bursie wrote:
>>> This bug is the continuation of JDK-8173303, in which Mandy added 
>>> the generation of .dot files for @moduleGraph Javadoc tags.
>>>
>>> With this patch, the code is taken to it's completion, and the 
>>> temporarily solutions left in place by JDK-8173303 has been replaced 
>>> by properly integrated solutions.
>>>
>>> Summary of changes:
>>> * A new option --enable-full-docs determines if module graphs should 
>>> be created or not. (In the future, even more optional but 
>>> "difficult" documentation work might be added to depend on this.) 
>>> This is enabled by default is all prerequisites are present.
>>> * It is not impossible to get to a state of the documentation with 
>>> broken img links.
>>> * I have re-introduced SetupJavadocGeneration to stop the code 
>>> duplication between JDK and Java SE javadoc builds.
>>> * I have fixed a bug in how the makefiles determines the 
>>> dependencies of modules. This only affected a single module in 
>>> nashorn, and no nashorn build code used these dependencies, so 
>>> that's why it has gone unnoticed until now. I have verified that no 
>>> other changes in module dependencies are introduced by this fix.
>>> * Javadoc source code dependencies are now correct even for 
>>> transitive modules
>>> * Support added for the creation and use in jib of a "graphviz" module.
>>>
>>> This code is dependent on JDK-8172312. This webrev is done as a diff 
>>> against the latest published webrev of JDK-8172312. JDK-8172312 is 
>>> reviewed, but is currently awaiting the status for JEP 299 to be 
>>> changed to Targeted before it can be pushed.
>>>
>>> This code only affects the build system and documentation. I intend 
>>> to push it to jdk9 using the "noreg-doc" RDP2 exception.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176785
>>> WebRev: 
>>> http://cr.openjdk.java.net/~ihse/JDK-8176785-full-build-support-for-module-graphs/webrev.01
>>>
>>
>