FMo*_*da3 3 java maven-2 documentation-generation apache-forrest
最近,我一直在研究Apache Forrest作为代码文档解决方案.来自Apache的网站,
"Apache Forrest™软件是一个发布框架,它将来自各种来源的输入转换为一种或多种输出格式的统一表示.Apache Forrest的模块化和可扩展的插件体系结构基于Apache Cocoon和相关的行业标准,将表示分开来自内容.Forrest可以生成静态文档,或者用作动态服务器,或者由其自动化工具部署."
我想知道Apache Forrest是否可以用作组织和发布一些Java代码的文档的方法,这些代码与JavaDoc注释一起完成.我知道JavaDoc可以自己做,但我觉得Apache Forrest提供了一些额外的自定义.我在Apache网站上找到了如何将其包含在Maven中的说明,但它似乎是针对Maven 1.x而定制的,我使用Maven 2.这样的事情可能吗？如果是这样,那么整合它的最佳方式是什么？
提前谢谢.
在使用Apache Forrest的Documenting Projects中,作者写了关于Forrest Alternatives的文章:
如果你熟悉Maven,你可能会想知道为什么有人会为Forrest打扰.Maven完成了Forrest所做的一切,以及更多:完全自动化构建,在基本文档之上附加JUnit和CVS报告以及各种其他有用信息.它甚至提供了将新生成的网站自动安装到远程主机上的目标.
我在许多项目中使用过Maven,这是一个令人印象深刻的包.学习曲线并不比Forrest的基本用途差,并且因为如果你使用Maven你不需要学习Ant,那么从头开始设置一个项目可能更少.但是,Forrest作为一个整体并不那么复杂,如果你不需要Maven提供的所有东西,你可能想要从Forrest开始并在以后需要时迁移到Maven.如果你有一个基于Ant的现有大型构建系统,Forrest也会更好:它允许你逐步添加Maven风格的网站生成,而不是将所有构建脚本重写为Maven-ize项目.
就纯文档替代方案而言,另一个具有大量开源社区支持的可靠选项是DocBook.您可以使用DocBook编写747手册:它是技术写作的最终SGML(或XML;有两个版本)方言.XML变体有一套很好的Norman Walsh样式表,可以从DocBook源生成HTML,PDF,RTF(Microsoft Word)和其他格式.我认为Forrest的XML方言覆盖了80%的案例,学习曲线要小得多,但对于需要制作印刷文档的大型项目,DocBook也值得考虑.请注意,如果要从DocBook迁移,Forrest也支持渲染DocBook/XML的子集,但它不受支持.根据其中一位开发人员的说法,Forrest并不打算在未来的任何时候成为一个成熟的DocBook渲染器,因此我不会依赖它作为Forrest新文档的格式.
所以,当你已经在使用Maven时,我真的很想知道你为什么要看福雷斯特.如果您对Maven的潜力仍有疑问,请查看Maven Doxia.
如果你想使用DocBook,如果Maven通过Doxia的原生支持太有限,那么就有Docbkx Maven插件(优于Maven Docbook插件).