Google Git
Sign in
apache / freemarker-docgen / 7ce98b3d10d25a1cb9d27a62b57ed5fe3e7b14a2
commit7ce98b3d10d25a1cb9d27a62b57ed5fe3e7b14a2[log] [tgz]
authorddekany <ddekany@apache.org>Sun Jul 12 02:14:44 2020 +0200
committerddekany <ddekany@apache.org>Sun Jul 12 02:14:44 2020 +0200
tree85073d9ab9f7fbb2dd2c4bf1b8e9cc02892df865
parent36e26561ecc50aee338d7a95fa4211a9f21b5862 [diff]
(Test script adjustment)
1 file changed
tree: 85073d9ab9f7fbb2dd2c4bf1b8e9cc02892df865
  1. freemarker-docgen-ant/
  2. freemarker-docgen-cli/
  3. freemarker-docgen-core/
  4. freemarker-docgen-maven/
  5. legacy-tests/
  6. xxe-addon/
  7. .eslintrc
  8. .fbprefs
  9. .gitattributes
  10. .gitignore
  11. .jshintrc
  12. .travis.yml
  13. checkstyle.xml
  14. DISCLAIMER
  15. ivy.xml
  16. ivysettings.xml
  17. LICENSE
  18. LICENSE-DOCBOOK-RNG
  19. NOTICE
  20. package-lock.json
  21. pom.xml
  22. rat-excludes
  23. README.md
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)
  • Node.js must be installed (tried with v10.16.2).
  • Go to freemarker-docgen-core, and issue npm install there to install Node.js dependencies. Repeat this step 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 (again, do the npm npm installation first!):

mvn install

For some examples see:

For editing DocBook, we are using XXE with the 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 Standard ASF release procedure. Binary release to Maven Central.

Icon Font Attribution

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