abbadon1334/phpdoc-to-rst

从PHPDoc生成Sphinx/ReStructured文档

1.1 2020-12-26 19:42 UTC

README

Codacy Badge Build Status Coverage Status Codacy Badge Codacy Badge

由Francesco "Abbadon1334" Danti进行分支和重构。

现在按预期工作,覆盖率良好。

## 从PHPDoc注释生成基于Sphinx的文档的reStructuredText。

该项目主要基于phpDocumentor/Reflection,并使用sphinxcontrib-phpdomain

可以在我们的自身文档中找到文档输出的示例。

快速入门

将phpdoc-to-rst安装到您的项目目录中

composer require --dev abbadon1334/phpdoc-to-rst

命令行使用

运行命令行工具,解析包含您的PHP树的文件夹,并将reStructuredText文件渲染到输出目录

php vendor/bin/phpdoc-to-rst generate --repo-base "$PWD" --repo-github https://github.com/abbadon1334/phpdoc-to-rst -t docs/rst/ src/

程序化使用以生成文档rst

    // your source path or multiple path to be parsed
    $src = [__DIR__.'/../src'];
    
    // destination path for the documentation
    $dst = __DIR__.'/../docs/api';
    
    $apiDocBuilder = new ApiDocBuilder($src, $dst);
    
    // DEBUG FATURES : optional
    // optional : activate verbosity
    $apiDocBuilder->setVerboseOutput(true);
    // optional : activate debug
    $apiDocBuilder->setDebugOutput(true);
    
    // EXTENSIONS : optional
        
    /**
     * Do not render classes marked with phpDoc internal tag
     * Do only render public methods/properties.
     */
    $apiDocBuilder->addExtension(PublicOnlyExtension::class);
        
    /**
     * Do not render classes marked with phpDoc internal tag
     * Do only render public methods/properties.
     */
    $apiDocBuilder->addExtension(NoPrivateExtension::class);
        
    /**
     * This extension will render a list of methods  for easy access
     * at the beginning of classes, interfaces and traits.
     */
    $apiDocBuilder->addExtension(TocExtension::class);
        
    /**
     * This extension adds a link to the source at github to all elements.
     *
     * Arguments
     * 0 => Url to the github repo (required)
     * 1 => Path to the git repository (required)
     * 2 => Branch to link to (default=master)
     */
    $apiDocBuilder->addExtension(GithubLocationExtension::class, [
        __DIR__.'/../src',
        'http://github.com/abbadon1334/phpdoc-to-rst/',
    ]);
    
    // Build documentation
    $apiDocBuilder->build();