0

Short version

We need a Maven Doxia alternative being able to generate good looking PDFs (at least code snippets should be properly indented and have configurable font size). Maven guys proposed maven-pdf-plugin in DOXIA-419, but it has same problems. Aforementioned DOXIA-419 has details on difficulties we've experienced with Doxia.

Detailed version

We develop a BIG product providing Java/C/C++/C#/etc API. Tens of client-customized branches are maintained/developed simultaneously. We need a tool to facilitate automatic document generation meeting these requirements:

  1. Include arbitrary snippets from Java/XML/etc samples. Confluence Snippet Plugin is a good example of this feature.

  2. Generate good looking printable documents (e.g. PDF).

  3. Generate online documents having clickable cross-references etc (e.g. HTML).

  4. Unattended mode (e.g. should be easy to run document generation process from Ant script).

  5. Documentation source content (from which PDFs/etc are later generated) should be kept in a human-readable easy-to-diff format.

  6. Documentation source content should be kept in separate files (not Java sources).

  7. Support (Java/xml/etc) syntax highlighting.

UPDATE: 8. Windows OS compatibility.

Jean-Rémy Revy
  • 5,607
  • 3
  • 39
  • 65
user648373
  • 9
  • 2

1 Answers1

3

My open source project Dexy might work for you. It's an authoring tool rather than an automatic document-generation tool, so it's not like JavaDoc which creates a whole structure automatically. Source code and document content are kept separate, syntax highlighting support is very good, document snippets are available. I use LaTeX for good looking printable documents, but you could use any other text-based format that compiled to PDF if you preferred that. Re the clickable cross references, you'd have to write HTML templates which could then be populated automatically (I'm doing so now, replacing JavaDoc on a project). You can also run live code examples and include this output in your documentation.

http://dexy.it

ananelson
  • 111
  • 2
  • From your description this firstly looked like right what we need. Unfortunately I forgot to mention we perform builds on Windows build servers, so ["very limited support for Dexy on Windows"](http://www.dexy.it/install/#windows) is confusing. Another point is I just cannot believe there is no windows-compatible industry-standard tool for such tasks. @ananelson, I suppose you've tried some tools, but didn't find the one to match your needs, right? What tools did you try and which one of win-compatible was most close to Dexy? – user648373 Mar 08 '11 at 15:19
  • I haven't spent much time looking for Windows-compatible tools I'm afraid, so I don't know what's out there. Windows support is available in Dexy as the code is in Python, but some of the filters currently depend on Python modules which are only compatible with Linux systems, and other filters have been written in such a way that they call tools with a Linux-specific format. These issues can be dealt with, just might take a little work. I don't know of any other tool which will handle all the languages you want in the way that you want, but that's not to say it doesn't exist. – ananelson Mar 10 '11 at 10:28