[
https://issues.apache.org/jira/browse/MJAVADOC-699?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Ernst Reissner updated MJAVADOC-699:
------------------------------------
Description:
For including math in api docs I use mathjax.
To that end i configure the javadoc plugin as follows:
{noformat}
<additionalOptions>
<additionalOption>-Xdoclint:all
-Xdoclint:-missing</additionalOption>
<additionalOption>--allow-script-in-comments</additionalOption>
</additionalOptions>
<header>
<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">
</script>
</header>
{noformat}
you can see that I download the config from
{noformat}
https://www.simuline.eu/MathJax/config/myDefault.js
{noformat}
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
was:
For including math in api docs I use mathjax.
To that end i configure the javadoc plugin as follows:
{noformat}
<additionalOptions>
<additionalOption>-Xdoclint:all
-Xdoclint:-missing</additionalOption>
<additionalOption>--allow-script-in-comments</additionalOption>
</additionalOptions>
<header>
<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">
</script>
</header>
{noformat}
you can see that I download the config from
{noformat}
https://www.simuline.eu/MathJax/config/myDefault.js
{noformat}
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').
> mathjax based on dependency
> ---------------------------
>
> Key: MJAVADOC-699
> URL: https://issues.apache.org/jira/browse/MJAVADOC-699
> Project: Maven Javadoc Plugin
> Issue Type: New Feature
> Components: javadoc
> Affects Versions: next-release
> Reporter: Ernst Reissner
> Priority: Major
>
> For including math in api docs I use mathjax.
> To that end i configure the javadoc plugin as follows:
> {noformat}
> <additionalOptions>
> <additionalOption>-Xdoclint:all
> -Xdoclint:-missing</additionalOption>
> <additionalOption>--allow-script-in-comments</additionalOption>
> </additionalOptions>
> <header>
> <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">
> </script>
> </header>
> {noformat}
> you can see that I download the config from
> {noformat}
> https://www.simuline.eu/MathJax/config/myDefault.js
> {noformat}
> 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
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
