To get started with Maven you only need to add the following snippet to your pom.xml in build/plugins
section:
<plugin>
<groupId>com.github.weekens</groupId>
<artifactId>easydoc-maven-plugin</artifactId>
<version>0.4.17</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
This will setup Easydoc for your project. By default, Easydoc will scan recursively your src/
directory and
pom.xml
file. Any docs found will be generated into target/easydoc/index.html
page.
Below are plugin configuration options that you can specify inside the configuration section
of the plugin declaration.
<plugin>
<groupId>com.github</groupId>
<artifactId>easydoc-maven-plugin</artifactId>
<version>0.4.17</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<b><configuration>
configuration options go here
</configuration></b>
</plugin>
Specifies the output directory for the generated documentation.
Default value: target/easydoc
<configuration> ... <sourceBrowser> <baseUrl>http://your.url.com/path_to_sources</baseUrl> <type>source_browser_type (covered below)</type> ... (other params if necessary) </sourceBrowser> </configuration>
github
GitHub source browser. To specify it, use the following snippet:<sourceBrowser> <type>github</type> <baseUrl>https://github.com/weekens/easydoc/blob/master/</baseUrl> </sourceBrowser>
fisheye
Fisheye source browser. To specify it, use the following snippet:<sourceBrowser> <type>fisheye</type> <baseUrl>https://mycompany.com/browse/myrepo/mysourcepath/</baseUrl> </sourceBrowser>
false
.
Specifies Easydoc artifacts of other projects to be combined with current project Combining docs.
The configuration looks like this:
<configuration>
...
<combineWith>
<item>
<groupId>com.mycompany</groupId>
<artifactId>my-remote-project</artifactId>
<version>0.0.1-SNAPSHOT</version>
</item>
<item>
<groupId>com.mycompany</groupId>
<artifactId>my-other-project</artifactId>
<version>0.0.1-SNAPSHOT</version>
</item>
<item>
<groupId>com.mycompany</groupId>
<artifactId>my-other-project</artifactId>
<version>0.0.1-SNAPSHOT</version>
<classifier>optionalClassifier</classifier>
</item>
...
</combineWith>
...
</configuration>
java -jar easydoc.jar [inputDirectory=mysrc customCss=src/resources/my.css ...other params...]
/* @@easydoc-start, id=jmx@@ <h1>JMX management</h1> The service can be managed by JMX. Just connect to port 1099 with jsonsole to manage stuff. @@easydoc-end@@ */ public class JmxManager { ... }The HTML between @@easydoc-start@@ and @@easydoc-end@@ tags (this construct is called the "doc") will get to generated index.html automatically after you run easydoc.
@@easydoc-start[optional parameters: paramName=paramValue, ...]@@ HTML documentation @@easydoc-end@@
#@@easydoc-start, ignore=#&\,@@ # # Lock, stock & 2 smoking barrels # #@@easydoc-end@@
Lock stock 2 smoking barrels
This section covers the additional Easydoc stuff. Generally, you don't need all this to get started with your documentation. However, for advanced development, some of the things from here you may find useful.
Sometimes you need to combine docs from different project into one single documentation site (page). This section describes how you can easily do that.
By default, Easydoc generates an additional artifact for your documentation named
So, for the remote project documentation that you need to combine with the current, you already have
a special Maven artifact, and the only thing that is left is to declare that artifact as a dependency.
But not in the Maven <dependencies>
section, but in Easydoc configuration element:
combineWith.
After you've done that - the documenation from the remote project will get to your current project's
documentation page. More over, you can interact with docs from the remote project - use them in
@@include@@
directives and belongs
parameters - because the artifact contains not only the
generated text, but the data model of the remote docs.
Example:
You've got 2 projects: my-lib and my-webapp (group id: com.mycompany
, version 0.0.1-SNAPSHOT).
Both are documented with Easydoc. But you need documentation from my-lib to be present in
documentation page of my-webapp. You do the following:
Build my-lib. The artifact my-lib-0.0.1-SNAPSHOT-easydoc.jar gets installed into local repository (or deployed into remote repository).
Specify the artifact from step 1 in combineWith parameter of Easydoc plugin configuration in my-webapp:
<configuration>
...
<combineWith>
<item>
<groupId>com.mycompany</groupId>
<artifactId>my-lib</artifactId>
<version>0.0.1-SNAPSHOT</version>
</item>
</combineWith>
...
</configuration>
Build my-webapp. The documentation of my-webapp will now contain documentation from my-lib.
The additional doc parameters.
Defines the format, in which the doc is written.
Currently supported:
The default format for the docs can be specified by the defaultFormat parameter and overriden individually for any doc.
The value is case-insensitive.
@@easydoc-start@@
Simple text and a directive: @@include, id=doc-to-include@@
@@easydoc-end@@
Copies a specified doc's text verbatim into this directive's location. This does not prevent the included doc from normal generation into a place where it belongs.
Parameters:
Example:
@@easydoc-start, id=to-include@@ I'm a doc to include. @@easydoc-end@@
@@easydoc-start@@
I'm a normal doc. @@include, id=to-include@@
@@easydoc-end@@
Result:
I'm a doc to include.
I'm a normal doc. I'm a doc to include.