Google Git
Sign in
apache / freemarker-docgen / f83222f60b7c98ec748a39de3d0ab9bb14adec8a
commitf83222f60b7c98ec748a39de3d0ab9bb14adec8a[log] [tgz]
authorddekany <ddekany@apache.org>Sun Jul 19 15:14:28 2020 +0200
committerddekany <ddekany@apache.org>Sun Jul 19 15:14:28 2020 +0200
treea675a7a8fc50847788e8faad92775a1b6bf5019b
parent9034e4bb551559b77c522739272a70d9119bca9b [diff]
Removed incubation DISCLAIMER
1 file changed
tree: a675a7a8fc50847788e8faad92775a1b6bf5019b
  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. ivy.xml
  15. ivysettings.xml
  16. LICENSE
  17. LICENSE-ISO-RELAX
  18. LICENSE-JING
  19. NOTICE
  20. pom.xml
  21. rat-excludes
  22. README.md
README.md

Docgen

About

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.

Usage

For some examples see:

For editing DocBook, we are using XXE, with the xxe-addon installed, that you can find in this project.

Building

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. (Node.js is only used to generate static content while building Docgen itself.)

Run these to build:

  1. In the freemarker-docgen-core directory (not in the top directory) issue:

    npm install

    This is to get our JavaScript dependencies, based on package.json.

  2. In the project top directory (freemarker-docgen) issue:

    mvn install

Node.js troubleshooting

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 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.

Running Docgen from your IDE

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

Compiling LESS and JS

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.

Releasing a new Docgen version

[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.

Icon Font Attribution

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