DocGenerator API: merging several generations

This article presents how to merge several generations using the docGenerator API. This can be useful if for example you want several applications to contribute to the same wiki, rather than relying on only one generation. To be able to do this, the api allows to:

• Define opaque articles, which are articles which can be used in references but are not generated. it will allow for another generator to generate the content associated with the article, and merge the articles from several generators
• Don't write the index article and if it already exist, or don't generate it at all
• Don't write the resources directory content and if it already exist, or don't generate it at all

Use case

A use case for merging several generations is if you have several applications which contribute to parts (i.e. articles) of the same wiki.

For example you can have:

• A MyMainApplication.jar application which generates some articles
• A MyOtherApplication.jar application which generates other specific articles

You might also want to be able to regenerate at will only part of the wiki, by running MyMainApplication.jar or MyOtherApplication.jar at will, and only update the articles which are produced by the associated application.

Configure the index generation

It is possible to configure if the index article will be written. This is specified through the DocGeneratorAPI.setIndexGenerationType(char) method:

• If the argument is FilegenerationType.GENERATE_NEVER, then the index article will not be written
• If the argument is FilegenerationType.GENERATE_IF_NOT_EXIST, then the index article will only be written if it does not exist
• If the argument is FilegenerationType.GENERATE_ALWAYS (the default), or all other values, then the index article will be written regardless if it exists or not

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);
      
   // don't generate the index file
   api.setIndexGenerationType(FilegenerationType.GENERATE_NEVER);      

   // create an article
   XMLArticle article = api.createArticle("article1");
         
   // add a sentence in the article
   api.addSentence(article, "this is the article");
         
   // generate the wiki
   api.writeContent();           

Configure the resources generation

It is possible to configure if the resources sub-directory will be written. This is specified through the DocGeneratorAPI.setResourcesGenerationType(char) method:

• If the argument is FileGenerationType.GENERATE_NEVER, then the index article will not be written
• If the argument is FileGenerationType.GENERATE_IF_NOT_EXIST, then the index article will only be written if it does not exist
• If the argument is FileGenerationType.GENERATE_ALWAYS (the default), or all other values, then the index article will be written regardless if it exists or not

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);
      
   // don't generate the resources files
   api.setResourcesGenerationType(FilegenerationType.GENERATE_NEVER);      

   // create an article
   XMLArticle article = api.createArticle("article1");
         
   // add a sentence in the article
   api.addSentence(article, "this is the article");
         
   // generate the wiki
   api.writeContent();           

Creating an opaque article

Several methods allow to create an opaque article, which is an article which can be used in references, but for which no file will be generated in the wiki:

• DocGeneratorAPI.createOpaqueArticle(String) create an opaque article with the specified description
• DocGeneratorAPI.createOpaqueArticle(String, boolean) create an opaque article with the specified description

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article which will be usable as a reference but will not be written
   OpaqueArticle opaqueArticle = api.createOpaqueArticle("the opaque article");
      
   // create a second article and adds a paragraph
   XMLArticle article2 = api.createArticle("the second article");
      
   // add a reference to the opaque article
   api.addReference(article2, "the opaque article", "the opaque reference");      
   // could also be done with:
   api.addReference(article2, opaqueArticle, "the reference");            

Setting a default content

It is possible to create an output file and set a default content for the opaque article if the article is not already existing. This avoids to make a reference to a non existing file if the other application did not create the article (yet). For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an opaque article
   OpaqueArticle opaqueArticle = api.createOpaqueArticle("the opaque article");
   opaqueArticle.setDefaultContent("Default content for the opaque article");