Sphinx and ReST can be used as generic documentation tools, in my experience. There's nothing about Sphinx which obligates you to only use it for Python-based projects. For example, in my work, I've used it to build a user guide and an XML-RPC API reference. In both cases, I had no use for sphinx.ext.autodoc or other Python-specific extras. The documentation was written "by hand," with mostly generic ReST directives, rather than the specialty directives provided by Sphinx. For what it's worth, I have not yet needed to create a custom ReST directive for non-Python documentation.
Even if you're working with a PHP project, I think you'll find Sphinx useful. For example most of the directives provided by the module specific markup are actually quite general. I don't see why you couldn't or wouldn't use these constructs to document stuff from languages other than Python. Likewise, Sphinx makes it pretty easy to show code examples in other languages. There's even a configuration value to change the default to any language which Pygments supports (which includes PHP). If you're feeling particularly ambitious, you could even create a Sphinx extension to pluck something relevant from your PHP code.
All that said, be sure to consider the audience for your documentation project. While I think Sphinx is an excellent tool and would recommend it for a wide range of documentation projects, if your audience is expecting something else, be mindful of that. For example, if you were documenting a Java project, much of your audience may be expecting Javadoc-style documents. If you deviate from that expectation, make sure it's not just for kicks (i.e., it gives you better docs than you'd get otherwise) and be prepared to (briefly) make the case for what you've done differently (e.g. with a FAQ answer or introduction).
Finally, any documentation is better than no documentation, regardless the tool used to create them. Use any tool that helps you, if it's the difference between getting something out there and not.
CakePHP is using Sphinx for its new documentation, and I wrote the phpdomain for sphinx. While there isn't a way to automatically include your php doc blocks into sphinx, I still think its one of the better documentation authoring tools available. Its great for more narrative style documentation. But with the phpdomain you can make api docs as well.
The Doctrine project, an ORM for PHP, uses Sphinx to generate their online documentation at www.doctrine-project.org. They use a custom pygment for PHP. The documentation is available on Github at https://github.com/doctrine/orm-documentation. It includes the custom PHP pygment css file.
Also the python-pygments package comes with many pygment styles which you can try out by changing the pygments_style = value in your sphinx conf.py configuration file. For example, to try out the pastie highlighting sytle, which is part of python-pygments, you use
As far as I'm concerned, you can document just about any syntax in Sphinx as far as you doesn't limit yourself with languages supported by autodoc. You can create beautiful API References using standard Sphinx directives like .. class, .. method, .. function and other. They work perfectly apart from the source code and doesn't require any automatic generation and linking to the sources.
You can also create generic admonitions with some special class, that you could later hook to CSS:
.. admonition Title
:class: Ololo
This text could be formatted any way you want, using the ``Ololo`` tag.
There are also roles (they allow custom classes too) and other means of adding text with some special formatting, if the original directives aren't sufficient to you.
If you decide to create your docs async from the source code, make sure you disable checking the code coverage and other code-related features in your conf.py or on project initiation.
PS: You can see a very good answer on elements with custom classes here.
发布评论
评论（5）
根据我的经验，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 样式的文档。如果您偏离了这种期望，请确保这不仅仅是为了好玩（即，它为您提供了比其他方式更好的文档），并准备好（简短地）证明您所做的不同（例如，使用常见问题解答或介绍）。
最后，任何文档都比没有文档好，无论创建它们的工具是什么。使用任何对您有帮助的工具，如果这是得到和不得到东西之间的区别。
Sphinx and ReST can be used as generic documentation tools, in my experience. There's nothing about Sphinx which obligates you to only use it for Python-based projects. For example, in my work, I've used it to build a user guide and an XML-RPC API reference. In both cases, I had no use for
sphinx.ext.autodocor other Python-specific extras. The documentation was written "by hand," with mostly generic ReST directives, rather than the specialty directives provided by Sphinx. For what it's worth, I have not yet needed to create a custom ReST directive for non-Python documentation.Even if you're working with a PHP project, I think you'll find Sphinx useful. For example most of the directives provided by the module specific markup are actually quite general. I don't see why you couldn't or wouldn't use these constructs to document stuff from languages other than Python. Likewise, Sphinx makes it pretty easy to show code examples in other languages. There's even a configuration value to change the default to any language which Pygments supports (which includes PHP). If you're feeling particularly ambitious, you could even create a Sphinx extension to pluck something relevant from your PHP code.
All that said, be sure to consider the audience for your documentation project. While I think Sphinx is an excellent tool and would recommend it for a wide range of documentation projects, if your audience is expecting something else, be mindful of that. For example, if you were documenting a Java project, much of your audience may be expecting Javadoc-style documents. If you deviate from that expectation, make sure it's not just for kicks (i.e., it gives you better docs than you'd get otherwise) and be prepared to (briefly) make the case for what you've done differently (e.g. with a FAQ answer or introduction).
Finally, any documentation is better than no documentation, regardless the tool used to create them. Use any tool that helps you, if it's the difference between getting something out there and not.
前几天刚刚发布：
http://mark-story.com/posts/view/sphinx-phpdomain-released
Just released a few days ago:
http://mark-story.com/posts/view/sphinx-phpdomain-released
CakePHP 使用 Sphinx 作为其新文档，我为 sphinx 编写了 phpdomain。虽然没有办法自动将 php 文档块包含到 sphinx 中，但我仍然认为它是可用的更好的文档创作工具之一。它非常适合更多叙事风格的文档。但是使用 phpdomain 您也可以制作 api 文档。
CakePHP is using Sphinx for its new documentation, and I wrote the phpdomain for sphinx. While there isn't a way to automatically include your php doc blocks into sphinx, I still think its one of the better documentation authoring tools available. Its great for more narrative style documentation. But with the phpdomain you can make api docs as well.
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 的一部分，您可以使用
The Doctrine project, an ORM for PHP, uses Sphinx to generate their online documentation at www.doctrine-project.org. They use a custom pygment for PHP. The documentation is available on Github at https://github.com/doctrine/orm-documentation. It includes the custom PHP pygment css file.
Also the python-pygments package comes with many pygment styles which you can try out by changing the pygments_style = value in your sphinx conf.py configuration file. For example, to try out the pastie highlighting sytle, which is part of python-pygments, you use
就我而言，您可以在 Sphinx 中记录几乎任何语法，只要您不限制自己使用 autodoc 支持的语言。您可以使用标准 Sphinx 指令（如
.. class、.. method、.. function等）创建漂亮的 API 引用。它们可以与源代码完美地分开，并且不需要任何自动生成和链接到源。您还可以使用一些特殊的类创建通用警告，稍后您可以将其连接到 CSS：
如果原始指令不足以你。
如果您决定从源代码异步创建文档，请确保在
conf.py中或在项目启动时禁用检查代码覆盖率和其他代码相关功能。PS：您可以在此处看到关于具有自定义类的元素的非常好的答案。
As far as I'm concerned, you can document just about any syntax in Sphinx as far as you doesn't limit yourself with languages supported by autodoc. You can create beautiful API References using standard Sphinx directives like
.. class,.. method,.. functionand other. They work perfectly apart from the source code and doesn't require any automatic generation and linking to the sources.You can also create generic admonitions with some special class, that you could later hook to CSS:
There are also roles (they allow custom classes too) and other means of adding text with some special formatting, if the original directives aren't sufficient to you.
If you decide to create your docs async from the source code, make sure you disable checking the code coverage and other code-related features in your
conf.pyor on project initiation.PS: You can see a very good answer on elements with custom classes here.