多编程语言API的文档

Question

我是使用多种编程语言开发的SDK团队的一员 - 目前是ObjC，C＃，ActionScript，Java（Android），后来我们还会有更多语言。

我们希望提供由两部分组成的文档：

1. 人类可读文档
2. API参考

这两部分之间存在联系：从人类可读的文档中我们可以链接到特定的类或方法，从API参考中我们可以链接到一个文档来解释使用类或方法的上下文。

我们目前正在使用sphinx的组合，用于人类可读的文档和API的语言特定工具，例如doxygen或asdoc

我在LeapMotion中看到，他们能够为多种编程语言（非人类语言）生成完整的文档，并在编程语言之间建立交叉链接。

问题

是否有人知道如何以某种方式完成此类文档系统，我们不必将人类可读文档中的每个更改复制到每种语言，并且语言之间存在交叉链接？

Answer 1

我整理了Leap Motion文档。我使用Sphinx创建docs包和Breatx插件，它基本上将Doxygen生成的XML文件导入到Sphinx项目中，用于doxygenated API引用（C ++，C＃，Java和Objective-C）。对于从所谓的“人类可读”页面到API引用的链接，我从.tag文件生成RST替换，Doxygen将为您生成。从API引用到“人类可读”页面的链接是正常的相对超链接（我应该添加更多）。

我使用Sphinx的条件内容功能为每种编程语言生成一组单独的文档（“人类可读”和API）。因此，可以根据需要为每种编程语言定制这些文章，并为当前语言提供正确的代码示例。因为每个文档集具有相同的结构，所以从一种语言切换到另一种语言并不困难。

我确实在页面模板中添加了一些自定义JavaScript，以帮助切换语言。

tl; dr：Sphinx，Breathe，Doxygen和少量自定义JavaScript。

如果您想进一步讨论，可以向我们的（Leap Motion）开发人员论坛发帖提问。我会看到它（Stackoverflow不适合正在进行的讨论）。

Answer 2

嗨Ido Ran，                     你指定的工具在工业上最适合用于文档目的，我担心还没有这样的工具可以提供人类和API参考。我个人最好的工具之一就是多用途的doxygen （人类和API）希望这会有所帮助。