Sphinx 是一个 Python 库，用于从一组 ReST 格式的文本文件生成漂亮的文档。不是用于全文搜索的工具
我也完全了解 doxygen / phpdoc 工具。我想弄清楚是否有一种方法可以使用 Sphinx 来记录 PHP 项目？甚至任何其他非 Python 语言？
【问题讨论】：
标签： php python-sphinx documentation-generation
根据我的经验，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 样式的文档。如果您偏离了这个期望，请确保它不仅仅是为了好玩（即，它为您提供比其他方式更好的文档）并准备（简要地）说明您所做的不同之处（例如常见问题解答或介绍）。
最后，有文档总比没有文档好，无论使用什么工具来创建文档。使用任何对您有帮助的工具，如果它是获得与否之间的区别。
【讨论】：
"by hand" 时，您的意思是没有自动文档，并且您确实在每一行中都输入了内容，对吗？还是引用的内容暗示了我不理解的内容？
【讨论】：
CakePHP 正在将 Sphinx 用于其新文档，而我为 sphinx 编写了 phpdomain。虽然没有办法自动将您的 php 文档块包含到 sphinx 中，但我仍然认为它是可用的更好的文档创作工具之一。它非常适合更多叙事风格的文档。但是使用 phpdomain 你也可以制作 api 文档。
【讨论】：
Doctrine 项目是一个 PHP 的 ORM，它使用 Sphinx 在www.doctrine-project.org 生成他们的在线文档。他们使用 PHP 的自定义 pygment。该文档位于 Github 上，地址为 https://github.com/doctrine/orm-documentation。它包括自定义 PHP pygment css 文件。
python-pygments 包还带有许多 pygment 样式，您可以通过更改 sphinx conf.py 中的 pygments_style = 值来尝试这些样式强>配置文件。例如，要试用 pastie 突出显示样式，它是 python-pygments 的一部分，您可以使用
pygments_sytle = 'pastie'
【讨论】：
就我而言，您可以在 Sphinx 中记录几乎任何语法，只要您不限制自己使用 autodoc 支持的语言。您可以使用标准 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的元素上看到一个很好的答案。
【讨论】：