Introduction

What is Easydoc?

Easydoc is a developer tool that makes it easy to create and maintain full and up-to-date project documentation. At the core of Easydoc is a simple idea: documentation shoud be in the source code.

What can I do with Easydoc?

With Easydoc you can develop and maintain a number of technical docs, including specifications, user manuals, installation and administration guides. A project WIKI can also be generated by this tool.

What are the advantages of Easydoc?

Easydoc generates all the documentation from your source code. Thus:

How to start using Easydoc?

Just put some docs into your sources within special @@easydoc-start@@ and @@easydoc-end@@ tags. Then include an easydoc-maven-plugin declaration into your pom.xml (if you use maven) - and you're done. Go check your target/easydoc folder.
If you don't use maven, just run a standalone easydoc binary in your project folder (already in alfa).

source

Maven integration

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.

source

Plugin configuration

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>

outputDirectory

Specifies the output directory for the generated documentation.

Default value: target/easydoc

source

inputDirectory

The input directory to scan for docs.

Default value: src

source

excludes

Files or directories that should be excluded from the scan. Follows the standard Maven path pattern syntax.

source

includes

Files or directories that should only be scanned. All the other files will be omited. Follows the standard Maven path pattern syntax.

source

customCss

A custom CSS style to use in generated HTML.

source

sourceBrowser

This parameter tells Easydoc how to generate the source links for your docs. If this parameter is present, Easydoc will generate HTML links to a place of origin of each of your docs, so that you can view them directly in the browser.

Generally, you specify it in the following manner:
<configuration>
	...
	<sourceBrowser>
		<baseUrl>http://your.url.com/path_to_sources</baseUrl>
		<type>source_browser_type (covered below)</type>
		... (other params if necessary)
	</sourceBrowser>
</configuration>
	 

baseUrl and type are the essential parameters that you will need to specify. The following type values are supported so far:

source

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>
 

Replace baseUrl value with the one from your GitHub repository.

source

fisheye

Fisheye source browser. To specify it, use the following snippet:
<sourceBrowser>
	<type>fisheye</type>
	<baseUrl>https://mycompany.com/browse/myrepo/mysourcepath/</baseUrl>
</sourceBrowser>

You need to check your Fisheye repository path by just going to the 'Source' section.

source

encoding

Sets up the encoding for the source file and the resulting HTML.
If the project.build.sourceEncoding property is defined, it is used by default. Otherwise, the default encoding setting is taken from JVM.

source

generateIndex

If set to 'true' (default), Easydoc will generate index for the documentation. If 'false', the index won't be generated.

source

defaultFormat

Sets the default format for the docs. If not specified, 'html' is default.

source

generateArtifact

By default, Easydoc will generate an additional artifact for your documentation, containing the generated pages along with docs model metadata. You can disable it by setting this parameter to false.

source

artifactClassifier

With this parameter, you may explicitly specify a classifier for an artifact, generated by Easydoc.

source

combineWith

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>

source

Running from command line

Easydoc can be run as a simple binary from command line.
java -jar easydoc.jar [inputDirectory=mysrc customCss=src/resources/my.css ...other params...]

Parameters, that you can optionally specify, are the same as in Maven plugin.

Note: Currently, only the simple string parameters are supported. Array parameters (such as includes and excludes) and structured parameters (such as sourceBrowser) support is coming soon.

source

Usage

The syntax

As we said before, all you need to do is to put some docs anywhere in your source code.
Here is an example:
/*
@@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.

So, generally, the doc syntax is:
@@easydoc-start[optional parameters: paramName=paramValue, ...]@@

HTML documentation

@@easydoc-end@@

source

Parameters

id

With this parameter you can define the unique identifier for the doc to reference it from elsewhere. Primarily, you use it together with belongs parameter to group docs and form the doc tree.

If the id is specified, the HTML anchor to this doc will be generated with this id, and the doc will be referenceable by adding #id_value to the page address.

Requirements:

The id you define should be unique across all docs in your code. If it is not, easydoc will fail.

source

belongs

This parameter lets you join the doc to another doc as a child. Thus, this doc's content will be generated inside the parent's HTML.

The value is a parent doc's id.

Requirements:

The parent doc with the specified id should be there. If there is no such doc, easydoc will fail.

source

ignore

With this parameter you can ignore certain characters in doc's text. Those characters won't get to the resulting HTML.

The value is a string of characters, which should be ignored. To ignore comma (','), escape it with backslash ('\,').

Example:
#@@easydoc-start, ignore=#&\,@@
#
# Lock, stock & 2 smoking barrels
#
#@@easydoc-end@@

will result in
Lock stock  2 smoking barrels

source

weight

Defines the weight of the doc. The greater the weight, the lower the doc goes on the resulting page amongst the siblings.

The value is an integer, which may be positive, negative or zero (default). There are also 2 special keywords for the value: min and max, which define minimal and maximal weight respectively.
If the weight of two sibling docs is the same, they go in occurence order (which is default).

source

Index generation

By default, easydoc will generate index (contents) for your documentation containing all the docs with ids, having a string less than 50 characters in their first line.

Index generation can be disabled by setting parameter generateIndex=false.

source

Advanced

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.

source

Combining docs

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 -easydoc.jar. This artifact is installed, deployed and tracked by Maven just like any other one.

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:

  1. Build my-lib. The artifact my-lib-0.0.1-SNAPSHOT-easydoc.jar gets installed into local repository (or deployed into remote repository).

  2. 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>
    
  3. Build my-webapp. The documentation of my-webapp will now contain documentation from my-lib.

source

Additional parameters

The additional doc parameters.

source

format

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.

source

Directives

Directives are special tags inside a doc text, which are replaced with some values, depending on a directive meaning. A doc can have any number of directives inside.
Example:

@@easydoc-start@@

Simple text and a directive: @@include, id=doc-to-include@@

@@easydoc-end@@
	

Each directive has a name and parameters. Some parameters may be optional, some may be required. See documentation for a concrete directive.

source

include

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.

source