[MJAVADOC-699] mathjax based on dependency

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Incomplete
• Affects Version/s: 3.4.0
• Component/s: javadoc
• Assignee: Unassigned
• Reporter: Ernst Reissner
• Created: 19/Nov/21 11:42
• Updated: 29/Oct/23 21:42
• Resolved: 29/Oct/23 21:42

Description

For including math in api docs I use mathjax.

To that end i configure the javadoc plugin as follows:

	  <additionalOptions>
	    <additionalOption>-Xdoclint:all -Xdoclint:-missing</additionalOption>
	    <additionalOption>--allow-script-in-comments</additionalOption>
	  </additionalOptions>
	  <header>
	    &lt;script type="text/javascript" 
	src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML,https://www.simuline.eu/MathJax/config/myDefault.js"&gt; &lt;/script&gt;
	  </header>

you can see that I download the config from

https://www.simuline.eu/MathJax/config/myDefault.js

I think this is not what I want to do, because it is public and unversioned.
Have a look at https://maven.apache.org/plugins/maven-javadoc-plugin/examples/help-configuration.html describing javadoc plugins concept for helpfiles:
it is based on dependencies.

This is a quite general solution also other plugins make use of
as summarized in https://adangel.org/2016/02/22/sharing-pmd-rulesets/:
It is on

• Checkstyle configuration
• PMD configuration
• FindBugs configuration
• Code-Formatting configuration for IDEs
• ...

My suggestion is to use that also for mathjax config and maybe also for the converter
which is http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML in my case but I would also prefer a local solution with specified version (in my case 'latest').

The suggestion is to make the javadoc configurable in the following way:
```
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.4.0</version>
<configuration>
<mathjax>
<renderer>path to rendererin dependency/myrenderer.txt</renderer>
<config>path to config in dependency/myconfig.js</config>
</mathjax>
</configuration>
<dependencies>
<dependency>
<groupId>com.mycompany.project</groupId>
<artifactId>configs</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
</dependencies>
</plugin>
```

This is much like the javadoc plugin allows for helpfiles.

The project in the dependency looks like so:
```
config-

pom.xml

src-main-resources-com-mycompany-project-configs

myrenderer.txt

myconfig.js ```

Here myconfig contains the config of mathjax in javascript
and myrenderer contains the url of the renderer.

To implement that, the javadoc plugin must only create two <script> sections in the header.

I hope I could have clarified what I mean.

and the artifact configs looks like that