|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectorg.codehaus.enunciate.modules.BasicDeploymentModule
org.codehaus.enunciate.modules.FreemarkerDeploymentModule
org.codehaus.enunciate.modules.docs.DocumentationDeploymentModule
public class DocumentationDeploymentModule
The documentation deployment module is responsible for generating the documentation for the API. This includes both the HTML pages and any other static content, e.g. client libraries.
The order of the documentation module is 100, essentially putting it after the generation of any static documents (e.g. WSDL, schemas) or static downloads (e.g. client libraries), but before the assembly of the war (see the spring-app module, order 200).
The only significant steps in the documentation module are the "generate" step and the "build" step.
During the generate step, the documentation deployment module generates an XML file that conforms to this schema containing all the documentation for the entire API in a structured form.
The build step is where all the documentation files are generated as needed and assembled into a single directory. The first step is to copy the static files (the "base") to the build directory. The documentation base can be specified in the configuration, or you can use the default base.
Then, the documentation module generates another XML file conforming to this schema that contains the information for the files available for download in a structured form. By default, all named artifacts are included as a download (see the architecture guide for details). Other downloads can also be specified in the configuration.
Finally, the XML generated in the generate phase and the XML generated for the download files is processed together to create the static documentation elements. By default, a Freemarker Processing Template is applied to process the XML. You can supply your own Freemarker processing template in the configuration, or you can supply a custom an XML Stylesheet Transformation to generate your site documentation. Click here to see the default Freemarker XML Processing Template used by Enunciate, which might be helpful as a starter for you to create your own custom one. Click here for an example XSLT file.
The configuration for the documentation deployment module is specified by the "docs" element under the "modules" element in the Enunciate configuration file.
There can be any number of "download" elements specified. This element is used to indicate another file or Enunciate artifact that is to be included in the "downloads" page. The download element supports the following attributes:
You can apply additinoal css files to the generated documentation. Use the "file" attribute to specify the additional css file to apply.
The documentation deployment module exports only one artifact: the build directory for the documentation. The artifact id is "docs", and it is exported during the "build" step.
| Field Summary |
|---|
| Fields inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule |
|---|
enunciate |
| Constructor Summary | |
|---|---|
DocumentationDeploymentModule()
|
|
| Method Summary | |
|---|---|
void |
addAdditionalCss(java.lang.String additionalCss)
Adds an additional css file to the generated documentation. |
void |
addDownload(DownloadConfig download)
Adds a download to the documentation. |
protected void |
buildBase()
Builds the base output directory. |
protected void |
doBuild()
Default implementation is a no-op. |
void |
doFreemarkerGenerate()
The generate logic builds the XML documentation structure for the enunciated API. |
protected void |
doFreemarkerXMLProcessing(java.net.URL freemarkerXMLProcessingTemplateURL)
|
protected void |
doXmlTransform()
Do the XSLT tranformation to generate the documentation. |
protected void |
doXSLT(java.net.URL xsltURL)
|
protected void |
generateDownloadsXML()
Generates the downloads xml indicating the available downloads. |
java.util.List<java.lang.String> |
getAdditionalCss()
The additional css files. |
java.lang.String |
getBase()
The documentation "base". |
org.apache.commons.digester.RuleSet |
getConfigurationRules()
Default implementation returns null. |
java.lang.String |
getCopyright()
The copyright (posted on the website). |
java.lang.String |
getCss()
The cascading stylesheet to use instead of the default. |
java.lang.String |
getDefaultNamespace()
The default namespace for the purposes of generating documentation. |
java.io.File |
getDocsBuildDir()
The directory into which the documentation is put. |
java.lang.String |
getDocsDir()
The subdirectory in the web application where the documentation will be put. |
protected java.net.URL |
getDocsTemplateURL()
The URL to the Freemarker template for processing the base documentation xml file. |
java.util.Collection<DownloadConfig> |
getDownloads()
The configured list of downloads to add to the documentation. |
protected java.net.URL |
getDownloadsTemplateURL()
The URL to the Freemarker template for processing the downloads xml file. |
java.net.URL |
getFreemarkerXMLProcessingTemplateURL()
The url to the freemarker XML processing template that will be used to transforms the docs.xml to the site documentation. |
java.lang.String |
getGroupRestResources()
How to group the REST resources together. |
java.lang.String |
getIndexPageName()
The name of the index page. |
java.lang.String |
getJavadocTagHandling()
JavaDoc tag handing. |
java.lang.String |
getName()
The name of the deployment module. |
protected freemarker.template.ObjectWrapper |
getObjectWrapper()
The object wrapper to use for the model. |
int |
getOrder()
The order of execution for the deployment module. |
protected java.lang.String |
getRelativePathToRootDir()
Get the relative path to the root directory from the docs directory. |
java.lang.String |
getSplashPackage()
The package that contains the splash page documentation for the API. |
java.lang.String |
getTitle()
The title of the documentation. |
void |
init(Enunciate enunciate)
Sets the enunciate mechanism. |
void |
initModel(EnunciateFreemarkerModel model)
Initialize the model. |
boolean |
isApplyWadlFilter()
Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically. |
boolean |
isApplyWsdlFilter()
Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically. |
boolean |
isDisableRestMountpoint()
Whether to disable the REST mountpoint documentation. |
boolean |
isForceExampleJson()
Whether to force example JSON. |
boolean |
isIncludeDefaultDownloads()
Whether to include the default downloads (named artifacts) in the downloads section. |
boolean |
isIncludeExampleJson()
Whether to include example JSON in the documentation. |
boolean |
isIncludeExampleXml()
Whether to include example XML in the documentation. |
protected java.io.InputStream |
loadDefaultBase()
Loads the default base for the documentation. |
void |
onClassesFound(java.util.Set<java.lang.String> classes)
Logic for handling a set of classes that were found on the Enunciate classpath. |
void |
setApplyWadlFilter(boolean applyWadlFilter)
Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically. |
void |
setApplyWsdlFilter(boolean applyWsdlFilter)
Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically. |
void |
setBase(java.lang.String base)
The documentation "base". |
void |
setCopyright(java.lang.String copyRight)
The copyright (posted on the website). |
void |
setCss(java.lang.String css)
The cascading stylesheet to use instead of the default. |
void |
setDefaultNamespace(java.lang.String defaultNamespace)
The default namespace for the purposes of generating documentation. |
void |
setDisableRestMountpoint(boolean disableRestMountpoint)
Whether to disable the REST mountpoint documentation. |
void |
setDocsDir(java.lang.String docsDir)
The subdirectory in the web application where the documentation will be put. |
void |
setForceExampleJson(boolean forceExampleJson)
Whether to force example JSON. |
void |
setFreemarkerXMLProcessingTemplate(java.lang.String freemarkerProcessingTemplate)
The Freemarker XML processing template file that will be used to transforms the docs.xml to the site documentation. |
void |
setFreemarkerXMLProcessingTemplateURL(java.net.URL freemarkerXMLProcessingTemplateURL)
The url to the freemarker XML processing template that will be used to transforms the docs.xml to the site documentation. |
void |
setGroupRestResources(java.lang.String groupRestResources)
How to group the REST resources together. |
void |
setIncludeDefaultDownloads(boolean includeDefaultDownloads)
Whether to include the default downloads (named artifacts) in the downloads section. |
void |
setIncludeExampleJson(boolean includeExampleJson)
Whether to include example JSON in the documentation. |
void |
setIncludeExampleXml(boolean includeExampleXml)
Whether to include example XML in the documentation. |
void |
setIndexPageName(java.lang.String indexPageName)
The name of the index page. |
void |
setJavadocTagHandling(java.lang.String javadocTagHandling)
The javadoc tag handling. |
void |
setSplashPackage(java.lang.String splashPackage)
The package that contains the splash page documentation for the API. |
void |
setTitle(java.lang.String title)
The title of the documentation. |
void |
setTitleConditionally(java.lang.String title)
Set the title for this project iff it hasn't already been set. |
void |
setXslt(java.lang.String xslt)
The stylesheet to use to generate the documentation. |
void |
setXsltURL(java.net.URL xslt)
Set the url to the xslt to use to generate the documentation. |
| Methods inherited from class org.codehaus.enunciate.modules.FreemarkerDeploymentModule |
|---|
close, doGenerate, getConfiguration, getModel, getModelInternal, getTemplateExceptionHandler, getTemplateLoader, processTemplate, processTemplate, processTemplate, processTemplate |
| Methods inherited from class org.codehaus.enunciate.modules.BasicDeploymentModule |
|---|
debug, doCompile, doPackage, getAliases, getBuildDir, getCompileDir, getEnunciate, getGenerateDir, getPackageDir, getValidator, info, isDisabled, setBuildDir, setCompileDir, setDisabled, setGenerateDir, setPackageDir, step, warn |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface org.codehaus.enunciate.modules.DeploymentModule |
|---|
close, getAliases, getValidator, isDisabled, step |
| Constructor Detail |
|---|
public DocumentationDeploymentModule()
| Method Detail |
|---|
public java.lang.String getName()
DeploymentModule
getName in interface DeploymentModulegetName in class BasicDeploymentModulepublic int getOrder()
DeploymentModule
getOrder in interface DeploymentModulegetOrder in class BasicDeploymentModulepublic void onClassesFound(java.util.Set<java.lang.String> classes)
EnunciateClasspathListener
onClassesFound in interface EnunciateClasspathListenerclasses - The classes that were found.public java.lang.String getSplashPackage()
public void setSplashPackage(java.lang.String splashPackage)
splashPackage - The package that contains the splash page documentation for the API.public java.lang.String getCopyright()
public void setCopyright(java.lang.String copyRight)
copyRight - The copyright (posted on the website).public java.lang.String getTitle()
getTitle in interface DocumentationAwareModulepublic void setTitle(java.lang.String title)
setTitle in interface DocumentationAwareModuletitle - The title of the documentation.public void setTitleConditionally(java.lang.String title)
setTitleConditionally in interface ProjectTitleAwaretitle - The title.public java.lang.String getJavadocTagHandling()
public void setJavadocTagHandling(java.lang.String javadocTagHandling)
javadocTagHandling - The javadoc tag handling.public void addDownload(DownloadConfig download)
download - The download to add.public java.util.Collection<DownloadConfig> getDownloads()
public void addAdditionalCss(java.lang.String additionalCss)
additionalCss - The additional css.public java.util.List<java.lang.String> getAdditionalCss()
public boolean isIncludeDefaultDownloads()
public void setIncludeDefaultDownloads(boolean includeDefaultDownloads)
includeDefaultDownloads - Whether to include the default downloads (named artifacts) in the downloads section.public boolean isIncludeExampleXml()
public void setIncludeExampleXml(boolean includeExampleXml)
includeExampleXml - Whether to include example XML in the documentation.public boolean isIncludeExampleJson()
public void setIncludeExampleJson(boolean includeExampleJson)
includeExampleJson - Whether to include example JSON in the documentation.public boolean isForceExampleJson()
public void setForceExampleJson(boolean forceExampleJson)
forceExampleJson - Whether to force example JSON.
public void setXslt(java.lang.String xslt)
throws java.net.MalformedURLException
xslt - The stylesheet to use to generate the documentation.
java.net.MalformedURLExceptionpublic void setXsltURL(java.net.URL xslt)
xslt - The xslt.
public void setFreemarkerXMLProcessingTemplate(java.lang.String freemarkerProcessingTemplate)
throws java.net.MalformedURLException
freemarkerProcessingTemplate - The Freemarker XML processing template file that will be used to transforms the docs.xml to the site documentation.
java.net.MalformedURLExceptionpublic java.net.URL getFreemarkerXMLProcessingTemplateURL()
public void setFreemarkerXMLProcessingTemplateURL(java.net.URL freemarkerXMLProcessingTemplateURL)
freemarkerXMLProcessingTemplateURL - The url to the freemarker XML processing template.public java.lang.String getCss()
public void setCss(java.lang.String css)
css - The cascading stylesheet to use instead of the default.public java.lang.String getBase()
public void setBase(java.lang.String base)
base - The documentation "base".protected java.net.URL getDocsTemplateURL()
protected java.net.URL getDownloadsTemplateURL()
public java.lang.String getDocsDir()
getDocsDir in interface DocumentationAwareModulepublic void setDocsDir(java.lang.String docsDir)
setDocsDir in interface DocumentationAwareModuledocsDir - The subdirectory in the web application where the documentation will be put.public boolean isApplyWsdlFilter()
public void setApplyWsdlFilter(boolean applyWsdlFilter)
applyWsdlFilter - Whether to apply a filter for the WSDL files that will attempt to resolve the soap paths dynamically.public boolean isApplyWadlFilter()
public void setApplyWadlFilter(boolean applyWadlFilter)
applyWadlFilter - Whether to apply a filter for the WADL files that will attempt to resolve the paths dynamically.public java.lang.String getIndexPageName()
getIndexPageName in interface DocumentationAwareModulepublic void setIndexPageName(java.lang.String indexPageName)
setIndexPageName in interface DocumentationAwareModuleindexPageName - The name of the index page.public boolean isDisableRestMountpoint()
public void setDisableRestMountpoint(boolean disableRestMountpoint)
disableRestMountpoint - Whether to disable the REST mountpoint documentation.public java.lang.String getDefaultNamespace()
public void setDefaultNamespace(java.lang.String defaultNamespace)
defaultNamespace - The default namespace for the purposes of generating documentation.public java.lang.String getGroupRestResources()
public void setGroupRestResources(java.lang.String groupRestResources)
groupRestResources - How to group the REST resources together.public java.io.File getDocsBuildDir()
public void init(Enunciate enunciate)
throws EnunciateException
BasicDeploymentModule
init in interface DeploymentModuleinit in class BasicDeploymentModuleenunciate - The enunciate mechanism.
EnunciateExceptionpublic void initModel(EnunciateFreemarkerModel model)
EnunciateModelAware
initModel in interface EnunciateModelAwareinitModel in class FreemarkerDeploymentModulemodel - The model to initialize.
public void doFreemarkerGenerate()
throws EnunciateException,
java.io.IOException,
freemarker.template.TemplateException
doFreemarkerGenerate in class FreemarkerDeploymentModuleEnunciateException
java.io.IOException
freemarker.template.TemplateException
protected void doBuild()
throws EnunciateException,
java.io.IOException
BasicDeploymentModule
doBuild in class BasicDeploymentModuleEnunciateException
java.io.IOException
protected void generateDownloadsXML()
throws java.io.IOException,
EnunciateException
java.io.IOException
EnunciateException
protected void buildBase()
throws java.io.IOException
java.io.IOException
protected void doXmlTransform()
throws java.io.IOException,
EnunciateException
java.io.IOException
EnunciateException
protected void doFreemarkerXMLProcessing(java.net.URL freemarkerXMLProcessingTemplateURL)
throws java.io.IOException,
EnunciateException
java.io.IOException
EnunciateException
protected void doXSLT(java.net.URL xsltURL)
throws java.io.IOException,
EnunciateException
java.io.IOException
EnunciateExceptionprotected java.lang.String getRelativePathToRootDir()
protected java.io.InputStream loadDefaultBase()
protected freemarker.template.ObjectWrapper getObjectWrapper()
FreemarkerDeploymentModule
getObjectWrapper in class FreemarkerDeploymentModulepublic org.apache.commons.digester.RuleSet getConfigurationRules()
BasicDeploymentModule
getConfigurationRules in interface DeploymentModulegetConfigurationRules in class BasicDeploymentModule
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||