-
Notifications
You must be signed in to change notification settings - Fork 200
Custom Skin
Note: The following applies to Enunciate version 2. For applying a custom skin to Enunciate 1.x, see Custom Skin (Version 1)
Enunciate generates its documentation by passing the data model provided by the "provider" modules (see Modules) through a Freemarker Template, which is used to write out the HTML files to a directory. After the HTML files are generated, Enunciate copies a set of "static assets" (images, css, javascript, etc.) into the directory. The set of static assets is referred to as the "documentation base".
There are multiple levels of customization that you can leverage when applying a different skin to Enunciate's generated documentation. From simplest-but-least-powerful to most-complex-but-most-powerful, these are:
- Replace the default CSS stylesheet.
- Provide additional CSS stylesheet(s).
- Provide a custom documentation base.
- Provide a custom Freemarker template.
Each of these customization points can be provided in one of two ways:
- The Enunciate configuration file.
- Classpath lookup, such that you can just include a jar on your Enunciate build classpath and Enunciate will automatically "find" your custom skin.
If you're happy enough with just adjusting some colors and fonts, you can apply your own CSS file(s) to the Enunciate-generated documentation.
<enunciate>
<modules>
<docs css="/path/on/filesystem/to/custom.css">
<additional-css file="/path/to/additional.css"/>
</docs>
</modules>
</enunciate>
Enunciate will look for a file at /META-INF/enunciate/css/style.css
on your classpath. If that file is found, it will be used as your custom CSS file.
A "documentation base" is the set of files that are used and referenced by the generated documentation, e.g. images and javascript files.
<enunciate>
<modules>
<docs base="/path/on/filesytem/to/zip/or/dir"/>
</modules>
</enunciate>
Enunciate will look for a file at /META-INF/enunciate/docs-base.zip
on your classpath. If that file is found, it will be used as your custom documentation base.
If you need custom HTML, you will have to provide a custom Freemarker transform that will do what you need. The easiest way to do this probably to start with Enunciate's default Freemarker template and edit it according to your needs. You'll want to refer to the Freemarker docs.
<enunciate>
<modules>
<docs freemarkerTemplate="/path/on/filesytem/to/template.fmt"/>
</modules>
</enunciate>