sphinx for php代码文档[关闭]

根据我的经验,sphinx和rest可以用作通用文档工具。sphinx并没有义务让您只在基于python的项目中使用它。例如,在我的工作中,我使用它构建了一个用户指南和一个XML-RPCAPI引用。在这两种情况下,我都没有用 sphinx.ext.autodoc 或其他特定于python的附加功能。文档是“手工”编写的,主要使用一般的rest指令,而不是sphinx提供的专业指令。值得一提的是,我还不需要为非python文档创建自定义rest指令。

即使您正在处理一个php项目,我认为您也会发现sphinx很有用。例如,大多数由 the module specific markup 实际上是相当普遍的。我不明白为什么你不能或者不愿意使用这些结构来记录来自python以外语言的东西。同样,斯芬克斯使 show code examples in other languages . 甚至还有一个配置值可以将默认值更改为pygments支持的任何语言(包括php)。如果你特别有野心,你甚至可以 create a Sphinx extension 从php代码中提取相关的内容。

尽管如此,请务必考虑文档项目的受众。虽然我认为sphinx是一个很好的工具,并且会推荐它用于各种文档项目,但是如果您的读者希望看到其他东西,请记住这一点。例如,如果你正在记录一个Java项目,那么你的许多观众可能都在期待JavaDoc风格的文档。如果你偏离了这一预期,确保这不仅仅是为了好玩(即,它给你提供了比你得到的更好的文档),并准备好(简要地)为你所做的事情做出不同的解释(例如,用常见问题解答或介绍)。

最后,不管使用什么工具创建文档,任何文档都比没有文档好。使用任何有助于你的工具,如果这是得到与没有得到的区别。

几天前刚刚发布: http://mark-story.com/posts/view/sphinx-phpdomain-released

cakephp使用sphinx作为新文档,我为sphinx编写了phpdomain。虽然没有办法将php文档块自动包含到sphinx中,但我仍然认为它是可用的更好的文档创作工具之一。它对于更多的叙述式文档非常有用。但是使用phpdomain,您也可以制作api文档。

docine项目是一个php的orm,它使用sphinx在 www.doctrine-project.org . 他们使用php的自定义pygment。github上的文档位于 https://github.com/doctrine/orm-documentation . 它包括定制的php pygment css文件。

也 python片段 包附带许多pygment样式,您可以通过更改 Pygments_样式= 狮身人面像的价值 康普 配置文件。例如,尝试 帕西蒂 突出显示sytle,这是python pygments的一部分,您可以使用

pygments_sytle = 'pastie'

就我而言,只要你不受autodoc支持语言的限制,你就可以用sphinx来记录任何语法。您可以使用标准sphinx指令创建漂亮的api引用,如 .. class , .. method , .. function 等等。它们与源代码完全分开工作,不需要任何自动生成和链接到源代码。

您还可以使用一些特殊类创建一般警告,稍后可以挂接到css:

.. admonition Title
   :class: Ololo

   This text could be formatted any way you want, using the ``Ololo`` tag.

如果原始指令不足以满足您的要求,还可以使用角色(它们也允许自定义类)和其他方式添加具有某些特殊格式的文本。

如果决定从源代码异步创建文档,请确保禁用检查 conf.py 或者在项目启动时。

ps:对于具有自定义类的元素,您可以看到一个很好的答案 here .