Root directories and packages

By default docJGenerator takes the content of only one input (root) directory, and generates the resulting wiki in one output directory. However, it is possible to:

• Use the content of several input directories to generate the resulting wiki
• Define for each root directory a specific package ID, and enforcing the references from one package to another

Use cases

This makes possible to define only one set of articles, but generates various resulting wikis depending on the generation configuration. Some use cases would be:

• Generating a documentation for both Open Source and Closed Source parts, generating a limited documentation for the Open Source users of the project, and a complete one for the Closed Source users of the project
• Don't include an unfinished part of your wiki in the generated result, but you have show errors for references to this part

Usage with one root directory

The simplest way to use the generator is to use it with only one input (root) directory. This usage is straightforward:

• The generator will look for all the articles, resources, and images in the unique root directory (recursively going into sub-directories), and generate the HTML wiki result in the output
• There is only one "namespace" for all articles, images and resources in the input directpries, which means that if the tool finds for example two images with the same ID, it will emit an error

Usage with more than one root directory

However, it is possible to define more than one root directory and merge the documentation from all these input directories in one output wiki. In that case, an index file should be specified. For example:

      java -jar docGenerator.jar -input=wiki/input;wiki2/input -index=myIndex.xml -output=wiki/output

Note that this file does not need to be in one of the root directories.

In that case, it is possible to define packages for each root directory to avoid name clashing between articles, resources, and images between two root directories. To do that, you can define package IDs for each root directory. These IDs work as namespaces for all references in the wiki.

Defining a package for a root

To define a package ID for a root directory, you have to create an XML file with only one "package" element. For example:

   <package package="mypackage"/>

There can be only one package defintion per root directory (only the first one will be taken into account, the others will be discarded).

Note that the name of a package can only contain letters, digits, "-" or "_" characters. For example, the following names are valid:

      MyPackage, ThePackage12, Another_Package, core-package

Grammar

See The package declaration Schema.

Using package IDs

The package ID is used as a namespace, and can be referenced in:

• Article references
• Images references
• Resources references
• Conditions

The way articles, images, and resources are found is:

• If the reference has no package attribute, the generator will look for references having the same package definition as the origin root (found within the same root directory)
• Else the generator will look for a reference in the specified package

Default imports

It is possible to define packages which will be imported by default in a package. For example:

   <package package="mypackage">
     <defaultImports>
       <import package="thePackage"/>
     </defaultImports>
   </package>

In that case, if the reference has no package attribute:

• The generator will first look for a reference in the same package
• Else it will look for a reference in one of the default import packages

Default imports on all packages

You can specify that a package has imports by default to all other packages by using the allImports element. For example:

   <package package="mypackage">
     <defaultImports>
       <allImports/>
     </defaultImports>
   </package>

In that case, if the reference has no package attribute:

• The generator will first look for a reference in the same package
• Else it will look for a reference in any other package

Using the inputs sub-directories

It is possible to specify that the inputs sub-directories will be used rather that directly the inputs directory, by using the inputsSubdirectories property. This can be useful if you have many packages and you don't want to specify each of them.

For example, suppose that we have three packages, named root1, root2, and root3:

      -- wikiSource
      ------ root1
      ------ root2
      ------ root3

You can specify the inputs by:

      java -jar docGenerator.jar -input=wikiSource/root1;wikiSource/root2;wikiSource/root2 -output=wiki

Or by using the inputsSubdirectories property:

      java -jar docGenerator.jar -input=wikiSource -inputsSubdirectories=true -output=wiki

Enforcing the dependencies between packages

It is possible to enforce the dependencies between packages by specifying the dependencies configuration property.

Example

The following example has two root directories:

• One defining the "package1" package
• One defining the "package2" package, with a default import to "package1"