问题标签 [documentation-generation]

似乎有大量的 Python 文档工具。我遇到的另一个是 epydoc。似乎 Sphinx 是事实上的标准，因为它用于生成官方 Python 文档。有人可以帮我整理一下 Python 文档工具的当前状态吗？

我正在尝试使这个片段工作：

也就是说，使用 include 指令将文件作为块引用包含在内。一旦进入块引用，指令就会被引用。我想要块引用中的文件内容。

知道怎么做吗？

我知道 Doxygen 可以生成文档。我正在寻找的是在 Xcode 中插入文档的快速方法，类似于 Eclipse 在编辑 Java 文件时所做的。

假设我有一个带有如下参数的 Objective-c 方法：

在 Eclipse 中，如果将光标放在方法上方并键入：/**<Enter>您将获得一个预先填充了@param和@return标记的 Javadoc 模板。

是否有可能在 Xcode 中实现类似的功能？输入后/**<Enter>，我想自动得到这个：

我已经编写了一个epytext到reST标记转换器，现在我想将整个库中的所有文档字符串从 epytext 转换为 reST 格式。

有没有一种聪明的方法来读取模块中的所有文档字符串并写回替换内容？

ps：也许是ast模块？

我想知道是否有某种方法可以做到这一点，或者即使应该这样做？我的想法很快就转向使用方法属性，因为它是一种元数据，但我不确定是否有任何用于此目的。现在，我只是使用 XML 注释<remark>标签来判断一个方法何时实现了某个接口。但这当然根本不是元数据的结构化形式。

也许自动代码文档系统已经可以通过代码解析这些信息，但对于阅读实际代码以便更轻松地遵循它的任何人来说，它仍然很有用。

我正在与一个从事大型软件项目的团队合作，我们有大量以 MS WORD 格式编写的文档，没有超链接索引，没有搜索能力。我们每天都在浪费时间试图找到确切的文件或参考资料。

我在想是否有办法甚至专业的工具可以将所有这些转换为 wiki 格式，并且可能通过一些手动（痛苦的）帮助组织成可以提高可访问性的东西。我使用 Google 桌面搜索让我的生活更轻松一些，但它不是最好的解决方案

我只是想知道你们中是否有人遇到过类似的问题以及这个问题的可能解决方案。

我最近一直在写很多 VC++ 2008 / CLI 软件，并且正在使用 C#/CLI 风格的文档：

我发现自己非常频繁地重新输入这些块，坦率地说，它变得重复了。当您创建新函数定义或更新现有定义时，有什么方法可以让 Visual Studio 自动创建/更新这些块？

我们正在使用 asp.net c# 开发一个非常复杂的电子商务门户，客户要求我们使文档与ebay api 文档非常相似（外观和感觉） 。

您知道他们使用的是哪种工具吗？如果没有，您是否知道任何可以配置为产生类似结果的工具？

如果我有一个用 Symfony [symfony-project.org] 框架（即 PHP）编写的基于 REST 的服务，是否有任何像样的工具/框架可以解析我的代码并生成 API 文档？

基于 Java 的框架 enunciate 具有类似于我需要的文档功能，您可以在此处查看此示例：http: //enunciate.codehaus.org/wannabecool/step1/index.html。

我了解基于 REST 的服务的前提应该是不言而喻的，但是我正在寻找可以为我生成此文档的东西，而无需手动编写所有端点、支持的格式、示例输出等。

谢谢

有没有人尝试从您的黄瓜场景中创建最终用户（可能在线，可能要打印）帮助/文档？或者使用 RSpec 和 Selenium RC 的功能截取屏幕截图以用于文档？

对于 Cucumber，我在想像：

翻译成文档：

如果要添加链接，请转到编辑博客文章页面。按“添加链接”按钮并在链接 URL 字段中键入 URL，例如“ http://stackoverflow.com ”。单击“确定”。

是否值得我花时间尝试，一方面，编写一些东西来将我的 Cucumber 功能解析为文档，另一方面，以创建良好文档的方式编写/构造我的 Cucumber 功能？如果结构没有太大变化，生成的文档最终会听起来很无聊吗？

有没有其他类似的想法？doxygen看起来更像是代码文档而不是最终用户文档。

自动截屏怎么样？这似乎是一条更有成效的道路——只需重用在 RSpec 测试失败时截屏的代码，并在规定的情况下截屏。有一个更好的方法吗？