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:
- The
freemarker-site
project - FreeMarker Manual source code
legacy-tests
in 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:
- JDK 8, tested with Oracle 1.8.0_212
- Apache Maven, tested with 3.6.1
- Node.js, tested with 12.18.2, 14.x.x maybe won't work. (Node.js is only used to generate static content while building Docgen itself.)
To build, ensure that npm
(from Node.js) is in the path, then in the top project directory
(freemarker-docgen
) issue this:
mvn install
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 picks up thePATH
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.
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:
-Ddocgen.generationTime=2020-07-15T17:00Z
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:
- Entypo by Daniel Bruce
- Font Awesome by Dave Gandy.
- Material Design Icons by Google