Apache FreeMarker Docgen is an internal project under the Apache FreeMarker TLP, used for generating the FreeMarker Manual, the FreeMarker homepage, and maybe some more.
Docgen generates static web pages from a DocBook 5 “book” XML. But, it only implements the small subset of DocBook elements that we actually use, and it has no backward compatibility guarantees.
For some examples see:
legacy-testsin this project
For editing DocBook, we are using XXE, with the
xxe-addon installed, which you can find in this project.
These tools must be installed:
To build, ensure that
npm (from Node.js) is in the path, then in the top project directory (
freemarker-docgen) issue this:
Possible node.js related problems and solutions:
npm: Open a new terminal (command window) so that it picks up the
PATHenvironment variable changes. Adjust it if necessary.
npm installto recreate it.
If you develop/debug Docgen, it‘s convenient to launch it from your IDE. As an example, let’s generate the FreeMarker Manual. For that, create a Run Configuration in you IDE, with main class
org.freemarker.docgen.cli.Main, and these command line arguments (replace
<FREEMARKER_PROJECT_DIR> with the actual directory):
<FREEMARKER_PROJECT_DIR>\src\manual <FREEMARKER_PROJECT_DIR>\build\manual offline=true
To ease comparing the outputs of different runs, you can set a fixed value for the last modification with a java argument like this:
This happens automatically during build, in the
generate-resources Maven phase. The generated output is in
target\resources-gulp, which will be included in the core jar artifact.
[TODO] Standard ASF release procedure (staging, voting, etc.), so that we can release to the Maven Central. Not advertised, no announcements, no backward compatibility promises, but makes building our dependent projects easier.
The icon font in this project was built using IcoMoon and contains selected icons from: