fj-doc-guides

Configuration migration from DocProcessConfig to FreemarkerDocProcessConfig

Index

This guide is needed only if the old configurations files doc-handler-facade.xml and/or the doc-process-config.xml are being used.

If you are already using the new freemarker-doc-process-1-0.xsd you do not need to read more.

At the beginning, Venus was using the DocProcessConfig facade to handle the generation pipeline.

Now it is strongly recommended to use the new FreemarkerDocProcessConfig facade.

It substitutes both the doc-handler-facade.xml and the doc-process-config.xml.

The needed steps depends on the specific project configuration, but can be summarized in :

1. Convert the doc-process-config.xml and doc-handler-facade.xml in freemarker-doc-process.xml

You can use the Doc Configuration Convert function from the online playground.

For instance starting from :

<doc-process>

   <chain id="test-chain">
   	<step id="step-01" defaultBehaviour="CONTINUE"
   		description="Test for coverage" 
   		type="test.org.fugerit.java.doc.base.coverage.ProcessStepCoverage"
   		param01="TEST">
   		<properties xmlPath="coverage/xml/default_doc_alt.xml"/>
   	</step>
   </chain>

</doc-process>

<doc-handler-config user-catalog="default-complete">

	<factory id="default-complete">
		<data id="md-ext" info="md" type="org.fugerit.java.doc.base.typehandler.markdown.SimpleMarkdownExtTypeHandler" />
	</factory>
	
</doc-handler-config>

The resulting freemarker-doc-process.xml should be :

<?xml version="1.0" encoding="utf-8"?>
<freemarker-doc-process-config
xmlns="https://freemarkerdocprocess.fugerit.org"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://freemarkerdocprocess.fugerit.org https://www.fugerit.org/data/java/doc/xsd/freemarker-doc-process-1-0.xsd" >

	<docHandlerConfig>
		<!-- Type handler for markdown format -->
		<docHandler id="md-ext" info="md" type="org.fugerit.java.doc.base.typehandler.markdown.SimpleMarkdownExtTypeHandler" />
        
	</docHandlerConfig>
    
	<docChain id="test-chain">
		<chainStep stepType="test.org.fugerit.java.doc.base.coverage.ProcessStepCoverage">
			<!-- custom step, additional configuration may be needed -->
		</chainStep>
	</docChain>
    
</freemarker-doc-process-config>

2. Create your FreemarkerDocProcessConfig instance

FreemarkerDocProcessConfig config = FreemarkerDocProcessConfigFacade.loadConfigSafe("cl://path/to/freemarker-doc-process.xml" );

3. Use new fullProcess() functions

String chainId = "test-chain";
DocProcessContext context = DocProcessContext.newContext( ... );
String type = "md";
FreemarkerDocProcessConfig config = FreemarkerDocProcessConfigFacade.loadConfigSafe("cl://path/to/freemarker-doc-process.xml" );
config.fullProcess( chainId, context, type, outputStream );

4. Any needed clean up

Remove your old doc-process-config.xml configuration and any obsolete file and method.

This site is open source. Improve this page.