Google Git
Sign in
apache / freemarker-docgen / 19b70a9b91d117bae588e5cfdfac9e9c3a6bf2a4
commit19b70a9b91d117bae588e5cfdfac9e9c3a6bf2a4[log] [tgz]
authorddekany <ddekany@apache.org>Wed Jul 08 23:21:05 2020 +0200
committerddekany <ddekany@apache.org>Wed Jul 08 23:21:05 2020 +0200
treed1cf87e4548a93df0108605d9e9e85fce5235160
parent948b7b614f644be1df73173ee171869bc5a66744 [diff]
Migrated build to maven
83 files changed
tree: d1cf87e4548a93df0108605d9e9e85fce5235160
  1. .settings/
  2. src/
  3. .eslintrc
  4. .fbprefs
  5. .gitattributes
  6. .gitignore
  7. .jshintrc
  8. .travis.yml
  9. checkstyle.xml
  10. DISCLAIMER
  11. gulp-output-copyright-header.txt
  12. gulpfile.js
  13. ivy.xml
  14. ivysettings.xml
  15. LICENSE
  16. LICENSE-DOCBOOK-RNG
  17. NOTICE
  18. package-lock.json
  19. package.json
  20. pom.xml
  21. rat-excludes
  22. README.md
  23. test.xml
README.md

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_212)
  • Apache Maven must be installed (tried with 3.6.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:

mvn install

For some examples see:

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

Try your modifications

If you want to try your modifications, let's say, by regenerating the FreeMarker Manual, just create a Run Configuration in you IDE, with main class org.freemarker.docgen.TransformCommandLine, then specify these command line arguments:

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 with a java argument like this:

-Ddocgen.generationTime=2020-07-15T17:00Z

Compiling LESS and JS

This happens automatically during build, in the generate-resources. The generated output is in target\resources-gulp.

Publishing a new Docgen version

TODO

Icon Font Attribution

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