使用Sphinx生成PHP代码文档？ [英] Generating PHP code documentation with Sphinx?

问题描述

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

我也非常了解doxygen/phpdoc工具。我想知道是否有办法使用Sphinx来记录PHP项目？甚至是任何其他非Python语言？

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

推荐答案

根据我的经验，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项目，那么您的很多读者可能会期待使用Java样式的文档。如果你偏离了这个期望，确保它不只是为了好玩(也就是说，它给你的文档比其他情况下更好)，并准备好(简短地)为你所做的不同之处辩护(例如，通过常见问题解答或介绍)。

最后，有文档总比没有文档好，无论创建文档的工具是什么。使用任何对你有帮助的工具，如果这是得到一些东西和不得到一些东西的区别。

这篇关于使用Sphinx生成PHP代码文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！