基于模型的项目文档生成

Question

在我的项目开发过程中，我发现自己生成了一些只有几段略有变化的大型文档。例如，相同的配置计划将在不同的项目中使用，但每个文档必须使用特定数据进行定制，并符合某些特定要求。 作为一个懒惰的人和模型驱动开发的粉丝，我一直在寻找优化这个过程的方法，我有这些选择：

• 文档模板 - 将主文档模板（演示文稿）与表单（模型）一起使用或将文档的编辑限制为仅几个关键字段，然后交叉引用输入的数据全部在文档上可以做到这一点......但我仍然觉得我可以将两个图层分开一些。
• UML建模 - 使用带有UML支持的CASE工具，我想我可以将我的文档建模为带注释的包和类，更改每个项目的模型并使用文档模板生成报告。问题是这些工具不是为处理大块文本而设计的，我在进展方面遇到了一些困难。
• 流程建模 - 使用Eclipse EPF https://www.eclipse.org/epf/似乎对我想要完成的事情有点过分。记住：我是一个懒惰的人。

我想向社群询问他们<基于模型的文档的经验或他们在整个软件开发周期中优化文档生成的方法。

Answer 1

我不确定我是否完全理解，如果这会错过标记，那么道歉。

我面临（我认为）类似的问题，内容与需要呈现的文档之间有很多：很多关系。例如，需要包含在需求中的“项目概述”文件，项目计划等。

到目前为止，我找到的最佳解决方案是：

1. 以Markdown格式编写每个部分。有一些很好的编辑器可以让Markdown简单高效（例如OSX上的Mou）。
2. 使用Pandoc将Markdown转换为重组文本（RST）。
3. 使用Sphinx从RST文件生成文档。

我有多个Sphinx文档模板，每个模板都将一些常见部分与特定于该文档的其他部分相结合。如果其中一个常见部分得到更新，则可以轻松重新生成要合并的所有文档。版本控制非常简单，因为源文件都是简单文本。 Sphinx还可以轻松生成多种格式：例如，html可以在线投放，或者pdf可以用于打印/分发。

您可以通过本地写入RST来删除对第2步的需要。对我来说，额外的步骤是值得的，因为我没有找到一个像Mou一样舒适或高效的RST编辑器。 YMMV当然。

这不是一个完美的解决方案：例如，跨部门创建链接并不容易。但总的来说，它适合我的需求。

第h。