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

[Erik Joelsson]

Looks good, thanks!

/Erik


On 2017-04-12 15:14, Magnus Ihse Bursie wrote:
> 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
>>>>
>>>
>>
>