java - Apache Forrest 作为代码文档解决方案

Question

最近，我一直在研究 Apache Forrest 作为代码文档解决方案。来自 Apache 的网站，

"Apache Forrest™ software is a publishing framework that transforms input from various sources into a unified presentation in one or more output formats. The modular and extensible plug-in architecture of Apache Forrest is based on Apache Cocoon and the relevant industry standards that separate presentation from content. Forrest can generate static documents, or be used as a dynamic server, or be deployed by its automated facility."

我想知道 Apache Forrest 是否可以用作组织和发布一些带有 JavaDoc 注释的 Java 代码文档的方式。我知道 JavaDoc 可以自己做，但我觉得 Apache Forrest 提供了一些额外的定制。我在 Apache 网站上找到了有关如何将其包含在 Maven 中的说明，但它似乎是针对 Maven 1.x 量身定制的，而我使用的是 Maven 2。这可能吗？如果是这样，集成它的最佳方式是什么？

提前致谢。

Answer 1

在Documenting Projects with Apache Forrest , 作者写了这篇关于 Forrest Alternatives 的文章:

If you're familiar with Maven, you may be wondering why anyone would bother with Forrest. Maven does everything Forrest does, and much more: completely automating your build, attaching JUnit and CVS reports and all sorts of additional useful information on top of the basic documentation. It even provides targets to auto-install your newly generated web site onto a remote host.

I have used Maven on a number of projects, and it's an impressive package. The learning curve is not much worse than Forrest's for basic use, and since you don't have to learn Ant if you use Maven, it's arguably even less for setting up a project from scratch. Forrest as a whole is less complex, though, and if you don't need everything Maven provides, you might want to start with Forrest and migrate to Maven later if you need it. Forrest is also better if you have an existing large-build system based on Ant: it lets you add in Maven-style web site generation incrementally instead of rewriting all your build scripts to Maven-ize the project.

In terms of pure-documentation alternatives, another solid option with a lot of open source community support is DocBook. You could write the manual for a 747 with DocBook: it's the ultimate SGML (or XML; there are two versions) dialect for technical writing. The XML variant has a nice set of stylesheets from Norman Walsh that can generate HTML, PDF, RTF (Microsoft Word) and other formats from DocBook source. I think Forrest's XML dialect covers 80 percent of the cases, with a much smaller learning curve, but for a large project that also needs to produce print documentation, DocBook merits consideration. Note that if you want to migrate from DocBook, Forrest supports rendering a subset of DocBook/XML as well, but it is not well supported. Forrest does not aim to become a full-fledged DocBook renderer any time in the future, either, according to one of the developers, so I would not rely upon it as a format for new documentation in Forrest.

既然您已经在使用 Maven，我真的很奇怪您为什么要看 Forrest。查看Maven Doxia如果您对 Maven 的潜力仍有疑问。

如果您想使用 DocBook，并且如果 Maven 通过 Doxia 的本地支持太有限，则有 Docbkx Maven Plugin (优于 Maven Docbook plugin )。