[MJAVADOC-827] addStylesheet Misaligned With stylesheetFile From Dependencies

[jira-importer]

Mark Michaelis opened MJAVADOC-827 and commented

In MJAVADOC-625 support for --add-stylesheet has been introduced as new configuration parameter {}<addStylesheets>{}. The code has some issues though with several side effects compared to <stylesheetFile> refering to a resource in a dependency.

First Issue: Javadoc writes to src/main/javadoc

Given a snippet configuration snippet like this:

 

<stylesheetfile>from-dependeny.css</stylesheetfile>
<addStylesheets>
  <addStylesheet>in-src-main-javadoc.css</addStylesheet>
</addStylesheets>

If Javadoc is generated, it writes the content of from-dependeny.css to {}src/main/javadoc{}.

 

This is caused by the check that should ensure, that <addStylesheets> is only used with an existing {}<stylesheetFile>{}.

Second Issue: Additional Stylesheets Not Read From Dependencies

Unlike {}<stylesheetFile>{}, files given in <addStylesheets> are not taken from dependencies which was expected by us.

Thus, the assumption would be, that this should work (now using the default stylesheet, not overriding {}<stylesheetFile>{}):

 

<addStylesheets>
  <addStylesheet>additional-from-dependency.css</addStylesheet>
</addStylesheets> 

This does won't work, because the corresponding code only respects the Javadoc-folder, thus src/main/javadoc and not any other – including resources provided by dependencies.

 

The Cause

The cause is located around these lines:

• maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java at maven-javadoc-plugin-3.11.2 · apache/maven-javadoc-plugin

First, getAddStylesheet does not get the javadocOutputDirectory as the parameter suggests, but instead {}getJavadocDirectory(){}.

First Issue: This causes the subsequent check for the main stylesheet file to exist to write to src/main/javadoc (due to the internal call to {}getResource(){}).

Second Issue: Unlike {}getStylesheetFile(){}, getAddStylesheet() does not invoke getResource() if a stylesheet file cannot be found. Instead, it just fails with an exception.

Kind of third issue (design scope): While getStylesheetFile() just complains, that files do not exist (but does not fail), getAddStylesheet() always fails, when a file does not exist. When fixing this issue, it needs to be decided, if this contract should be kept as is, or if we just forward to getResource() as final fallback without raising an extra exception.

Regarding the very similar approach, both behaviors should be aligned here, so that I would vote for skipping the exception and leave it at a warning instead.

Workaround

There are several workarounds, like first unpacking resources via dependency plugin. I preferred using <resourceArtifacts> and subsequent <additionalOptions> to bypass the invalid check in {}getAddStylesheet(){}:

<configuration>
  <resourcesArtifacts>
    <resourcesArtifact>
      <groupId>com.mycompany</groupId>
      <artifactId>common-javadoc-resources</artifactId>
      <version>${project.version}</version>
    </resourcesArtifact>
  </resourcesArtifacts>
  <additionalOptions>
    <additionalOption>--add-stylesheet</additionalOption>
    <additionalOption>additional-from-dependency.css</additionalOption>
  </additionalOptions>
</configuration>

---

Affects: 3.3.0, 3.11.2

Issue Links:

• MJAVADOC-625 Support for multiple stylesheets

1 votes, 2 watchers