Don't use this repo anymore as it has moved to https://git-wip-us.apache.org/repos/asf/incubator-freemarker-docgen.git

GitHub mirror (read only): https://github.com/apache/incubator-freemarker-docgen

Visit http://freemarker.org/ for more information!

Discalimer regarding the usage of the Apache name

Apache FreeMarker is an effort undergoing incubation at The Apache Software Foundation (ASF). Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

---

Docgen

About

Docgen was originally written to generate HTML pages from the DocBook 5 XML that the FreeMarker Manual is written in. As such, it's not a general purpose DocBook 5 to HTML converter, however, we use it for other projects as well, so it's not entirely specialized either.

Requirements

You must have the following libraries installed to build this project:

• Java 8
• NodeJS 0.10 or higher
• Apache Ant

Usage

Before building for the first time:

• JDK 8 must be installed (tried with 1.8.0_20)
• Apache Ant must be installed (tried with 1.8.1).
• Node.js must be installed (tried with v0.10.32).
• Create a build.properties file based on build.properties.sample
• Issue npm install from the project directory to install Node.js dependencies. This need to be repeated if you add new dependencies to gulpfile.js.

To build Docgen:

ant all

This will create lib/docgen.jar and build/api.

For documentation see build/api/index.html. Especially, read the documentation of the Transform class there.

For some examples see src/test and test.xml, and of course, src/manual in the freemarker project.

For editing DocBook, we are using XXE with the src/xxe-addon installed.

Building tricks

If you run into dependency errors, you may need to issue:

ant update-deps

If you have modified docgen, and want to try the new version in the freemarker project, you will have to issue:

ant publish-override

This will shadow the docgen artifact that comes from the Ivy repo on freemarker.org. Then, in the freemarker project you have to issue ant update-deps so that it picks up your version.

Compiling LESS and JS

To compile LESS and JS separately from the regular ant build, run:

ant gulp

Eclipse and other IDE-s

You need to run this:

ant ide-dependencies

This will create an ide-dependencies library that contains all the jars that you have to add to the classpath in the IDE. Note that here we assume that you have run the build or at least ant update-deps earlier.

You could also use IvyDE instead, with configuration "IDE", but as the dependencies hardly ever change, it's unnecessary.

Icon Font Attribution

The icon font in this project was built using IcoMoon and contains selected icons from:

• Entypo by Daniel Bruce
• Font Awesome by Dave Gandy.
• Material Design Icons by Google