abbadon1334/phpdoc-to-rst

Generate Sphinx/ReStructured documentation from PHPDoc

1.1 2020-12-26 19:42 UTC

Requires

• nikic/php-parser: ^4.0
• phpdocumentor/reflection: ~4.0
• symfony/console: ^4.0

Requires (Dev)

• codacy/coverage: dev-master
• phpunit/phpunit: *

AGPL-3.0-or-later

• Francesco Danti
• Julius Härtl
• Ferenc Kurucz

README

Forked and refactor by Francesco "Abbadon1334" Danti.

Now working as intended, with good coverage.

##Generate reStructuredText for Sphinx based documentation from PHPDoc annotations.

This project is heavily based on phpDocumentor/Reflection and makes use of sphinxcontrib-phpdomain.

An example for the documentation output can be found in our own documentation

Quickstart

Install phpdoc-to-rst to your project directory:

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

Command line usage

Run the command line tool to parse the folders containing your PHP tree and render the reStructuredText files to the output directory:

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

Programatically usage to generate documentation 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();