Question

Sphinx是一个Python库，可以从一组ReST格式的文本文件生成漂亮的文档。不是用于全文搜索的工具

我也完全了解doxygen / phpdoc工具。我想弄清楚是否有办法使用Sphinx来记录php项目？甚至任何其他非python语言？

http://sphinx.pocoo.org/

Answer 1

根据我的经验，Sphinx和ReST可以用作通用文档工具。没有关于Sphinx的任何内容，只允许您将它用于基于Python的项目。例如，在我的工作中，我用它来构建用户指南和XML-RPC API参考。在这两种情况下，我都没有使用sphinx.ext.autodoc或其他特定于Python的附加功能。该文档是“手工”编写的，主要是通用的ReST指令，而不是Sphinx提供的专业指令。对于它的价值，我还不需要为非Python文档创建自定义ReST指令。

即使您正在使用PHP项目，我认为您会发现Sphinx非常有用。例如，the module specific markup提供的大多数指令实际上都很普遍。我不明白为什么你不能或不会使用这些结构来记录Python以外的语言。同样，Sphinx使show code examples in other languages变得非常容易。甚至还有一个配置值可以将默认值更改为Pygments支持的任何语言（包括PHP）。如果您感觉特别雄心勃勃，甚至可以create a Sphinx extension从您的PHP代码中提取相关内容。

所有这一切，请务必考虑您的文档项目的受众。虽然我认为Sphinx是一个很好的工具，并且会推荐它用于各种文档项目，如果您的观众期待其他东西，请注意这一点。例如，如果您正在记录Java项目，那么您的大多数受众可能会期待Javadoc样式的文档。如果你偏离了这种期望，那么确保它不只是为了踢（即，它给你提供比你更好的文档更好的文档）并且准备好（简要地）为你所做的事情做出不同的判断（例如，常见问题答案或介绍。）

最后，任何文档都比没有文档更好，无论用于创建它们的工具如何。使用任何可以帮助你的工具，如果在那里得到一些东西之间的区别是不同的。

Answer 2

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

Answer 3

CakePHP正在使用Sphinx作为其新文档，我为sphinx编写了phpdomain。虽然没有办法自动将你的php doc块包含到sphinx中，但我仍然认为它是一种更好的文档创作工具。它非常适合更多叙事风格的文档。但是使用phpdomain你也可以制作api文档。

Answer 4

Doctrine项目是PHP的ORM，它使用Sphinx在www.doctrine-project.org生成在线文档。他们使用PHP的自定义pygment。该文档可在https://github.com/doctrine/orm-documentation的Github上获得。它包括自定义PHP pygment css文件。

此外， python-pygments 包中还有许多段样式，您可以通过更改sphinx中的 pygments_style = 值来尝试 conf.py 配置文件。例如，要试用 pastie 突出显示sytle，它是python-pygments的一部分，你可以使用

pygments_sytle = 'pastie'

Answer 5

就我而言，只要您不限制使用autodoc支持的语言，就可以记录Sphinx中的任何语法。您可以使用标准的Sphinx指令（如.. class，.. method，.. function等）创建漂亮的API参考。它们与源代码完全不同，不需要任何自动生成和链接源。

您还可以使用某些特殊类创建通用警告，以后可以将其挂钩到CSS：

.. admonition Title
   :class: Ololo

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

如果原始指令不够用，还有角色（它们也允许自定义类）和其他用一些特殊格式添加文本的方法。

如果您决定从源代码创建文档异步，请确保在conf.py或项目启动时禁用检查代码覆盖率和其他与代码相关的功能。

PS：您可以在自定义类here的元素上看到非常好的答案。

用于php代码文档的Sphinx

5 个答案: