Google Git
Sign in
apache / freemarker-docgen

Apache Freemarker docgen

Mirrored from http://gitbox.apache.org/repos/asf/freemarker-docgen.git
Clone this repo:

Branches

Tags

  1. dd4694a Upgraded FreeMarker dependency by ddekany · 5 months ago master
  2. c348649 Updated Gulp stack further by ddekany · 5 months ago
  3. 5470c64 Updated XXE addon howto.txt by ddekany · 5 months ago
  4. 517a8f3 Updated Nodejs/Gulp stack by ddekany · 5 months ago
  5. 6cd302f (Updated eclipse project) by ddekany · 1 year ago

Docgen

About

Docgen is used to generate HTML pages from the two DocBook 5 “book” XML-s that the FreeMarker Manual and the FreeMarker homepage is written in. As such, it mostly only implements the subset of Docgen elements that we actually use, but otherwise it tries to be reusable in other projects as well.

Building

Before building for the first time:

  • JDK 8 must be used (tried with 1.8.0_20)
  • Apache Ant must be installed (tried with 1.8.1), and use JDK 8 for building.
  • Node.js must be installed (tried with v10.16.2).
  • 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.

Possible node.js related problems and solutions:

  • “Error: ENOENT, stat ”: create that directory manually, then retry.
  • If the system doesn't find npm: Open a new terminal (command window) so that it pick up the “path” environment variable changes. Adjust it if necessary.
  • If the build has once worked, but now keeps failing due to some missing modules, or anything strange, delete the “node_modules” directory, and issue npm install to recreate it.

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:

For editing DocBook, we are using XXE with the src/xxe-addon installed. Unfortunatelly, the free edition of XXE was discontinued long ago, but if there are problems with the old free version, or you will do serious amount of editing, we can contact XMLmind for more free licenses (in exchange for showing their logo on the generated pages).

Building tricks

Update dependencies

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

ant update-deps

Compiling LESS and JS

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

ant gulp

Trying modifications without publishing

If you have modified docgen and want to try the new version then we don‘t recomment doing that with Ant, because it’s slow and also tricky if you need to try it in a dependent project. Instead, see the IDE section later.

But if you must do it with Ant, issue:

ant publish-override

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

Eclipse and other IDE-s

Add project dependencies

You need to run this:

ant ide-dependencies

This will create an ide-dependencies directory 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 name “IDE”, but as the dependencies hardly ever change, it's unnecessary.

Try your modifications

If you want to try your modifications, let‘s say, by regenerating the FreeMarker Manual, don’t fiddle with Ant. Just create a Run Configuration in Eclipse with main class org.freemarker.docgen.TransformCommandLine, then on the “Arguments” tab enter “Program arguments” like:

C:\work\freemarker\git\freemarker-2.3-gae\src\manual
C:\work\freemarker\git\freemarker-2.3-gae\build\manual
offline=true

To ease comparing outputs, you can set a fixed value for the last modification time in the “VM arguments” box be entering something like:

-Ddocgen.generationTime=2015-12-19T17:00Z

Publishing a new Docgen version

As of this writing, the “docgen” dependency is get by freemarker and sitefrom the Ivy repo on http://freemarker.org/repos/ivy/. Those modifying docgen should upload the fresh docgen.jar there occasonally. For that, first issue:

ant server-publish-last-build

This won't actually upload anything, but you will find the directory structure to upload in the build/dummy-server-ivy-repo directory. See the README file in the site Git repo on how to upload content to the FreeMarker homepage!

Icon Font Attribution

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