php - 使用 Sphinx 生成 PHP 代码文档？

Question

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

我也完全了解 doxygen / phpdoc 工具。我想弄清楚是否有一种方法可以使用 Sphinx 来记录 PHP 项目？甚至任何其他非 Python 语言？

https://www.sphinx-doc.org/en/master/

Answer 1

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

即使您正在使用 PHP 项目，我想您也会发现 Sphinx 很有用。例如，模块特定标记提供的大多数指令实际上是非常通用的。我不明白为什么您不能或不会使用这些结构来记录来自 Python 以外的其他语言的内容。同样，Sphinx 可以很容易地显示其他语言的代码示例。甚至还有一个配置值可以将默认值更改为 Pygments 支持的任何语言（包括 PHP）。如果你感觉特别有野心，你甚至可以创建一个 Sphinx 扩展来从你的 PHP 代码中提取一些相关的东西。

话虽如此，请务必考虑您的文档项目的受众。虽然我认为 Sphinx 是一款出色的工具，并且会在各种文档项目中推荐它，但如果您的听众期待其他东西，请注意这一点。例如，如果您正在记录一个 Java 项目，那么您的大部分听众可能会期待 Javadoc 样式的文档。如果您偏离了这个期望，请确保它不仅仅是为了好玩（即，它为您提供比其他方式更好的文档）并准备（简要地）说明您所做的不同之处（例如常见问题解答或介绍）。

最后，任何文档都比没有文档好，无论用于创建它们的工具。使用任何对您有帮助的工具，如果它是获得与否之间的区别。

Answer 2

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

Answer 3

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

Answer 4

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 =值来尝试。例如，要尝试作为 python-pygments 一部分的paste突出显示样式，您可以使用

pygments_sytle = 'pastie'

Answer 5

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

您还可以创建带有一些特殊类的通用警告，稍后您可以将其挂接到 CSS：

.. admonition Title
   :class: Ololo

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

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

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

PS：您可以在此处看到有关具有自定义类的元素的非常好的答案。