PHPDOC 注释块与 Sphinx-doc (php.autodoc) 集成的 DIY 解决方案

Question

• JS 有：https://github.com/erikrose/sphinx-js
• Python 有它：http://www.sphinx-doc.org/en/master/ext/autodoc.html
• Java 有它：http://bronto.github.io/javasphinx/
• Swift 有它：https://github.com/AnarchyTools/anarchy_sphinx#swift-auto-documentation-extractor

PHP 仍然没有从源代码中提取文档的工具。

您能否建议如何将 PHPDOC 注释从我的 PHP 代码中自动提取到我用 sphinx（上下文）编写的文档中，如果没有这样的解决方案，如何制作一个（例如使用https://github.com/nikic/PHP-Parser/tree/3.x）？

谢谢！

Answer 1

2019 年更新

使用类似于 php-parser 的最佳工具是https://github.com/phpstan/phpdoc-parser

我将它与 php-parser 一起使用来以任何可能的方式操作 PHP，并且它可以很好地协同工作。

Answer 2

我今天实际上也有同样的问题，我发现这个工具可以为目录中命名空间的每个文件生成 reStructuredText：https://github.com/varspool/sphpdox/

目录结构，假设你已经使用 composer 安装了sphpdox，并在你的文档文件夹中运行sphinx-quickstart（在http://www.sphinx-doc.org/en/master/usage/quickstart.html 中有详细说明）（我在这个例子中使用了docs/：

src/
    YourNameSpace/
        YourClass.php
docs/
    Makefile
    source/
        index.rst
        conf.py
vendor/
    bin/
        sphpdox

要为您的命名空间生成 reST，您现在可以运行：

./vendor/bin/sphpdox process "YourNameSpace" ./src -o ./docs/source

这将在./docs/source/YourNameSpace创建一个目录

要使用 Sphinx PHP 域（sphpdox 使用），您必须安装 sphinxcontrib-phpdomain：

pip3 install sphinxcontrib-phpdomain

现在将它添加到扩展列表中：

# ./docs/source/conf.py
extensions = [
    # ...
    "sphinxcontrib.phpdomain"
]

现在您可以链接到 sphinx 索引中生成的目录：

# ./docs/source/index.rst

.. toctree::
    YourNameSpace/index

要使用构建器生成输出，现在运行make [builder]（例如make html）

要在运行构建器时自动生成 PHP reST 文件，您可以修改 Makefile:

# ./docs/Makefile

php:
    @../vendor/bin/sphpdox process "YourNameSpace" ../src/ -o ./source

%: php
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)