generate-function-docs

#!/usr/bin/env php
<?php

require_once 'vendor/autoload.php';

use Cache\Adapter\Redis\RedisCachePool;
use function Datashaman\PHPCheck\repr;
use Github\Client;
use phpDocumentor\Reflection\DocBlockFactory;
use Symfony\Component\Templating\Loader\FilesystemLoader;
use Symfony\Component\Templating\PhpEngine;
use Symfony\Component\Templating\TemplateNameParser;

$client = new Redis();
$client->connect('127.0.0.1', 6379);

$pool = new RedisCachePool($client);

$client = new Client();
$client->addCache($pool);

$client->authenticate(getenv('GITHUB_TOKEN'), null, Client::AUTH_URL_TOKEN);

$gists = $client->api('user')->gists('datashaman');

$parser = new Parsedown();

function markdown($text)
{
    global $parser;

    return $parser->text($text);
}

function getArguments($function, $docBlock = null)
{
    $tags = [];

    if ($docBlock) {
        $tags = array_reduce(
            $docBlock->getTagsByName('param'),
            function ($acc, $tag) {
                $name = $tag->getVariableName();

                $acc[$name] = [
                    'type' => (string) $tag->getType(),
                    'description' => preg_replace('#(^\<p>|\</p>$)#', '', markdown((string) $tag->getDescription())),
                ];

                return $acc;
            },
            []
        );
    }

    return array_map(
        function ($param) use ($tags) {
            $name = $param->getName();

            $arg = [
                'default' => null,
                'description' => isset($tags[$name]['description'])
                    ? $tags[$name]['description']
                    : null,
                'name' => $name,
                'type' => isset($tags[$name]['type'])
                    ? $tags[$name]['type']
                    : ($param->hasType() ? $param->getType() : false),
                'variadic' => $param->isVariadic(),
            ];

            if ($param->isDefaultValueAvailable()) {
                if ($param->isDefaultValueConstant()) {
                    $arg['default'] = $param->getDefaultValueConstantName();
                } else {
                    $arg['default'] = repr($param->getDefaultValue());
                }
            }

            return $arg;
        },
        $function->getParameters()
    );
}

function getDocBlock($function)
{
    $factory = DocBlockFactory::createInstance();
    $docComment = $function->getDocComment();

    return $docComment
        ? $factory->create($docComment)
        : null;
}

function getDescription($docBlock)
{
    return markdown(preg_replace('#\s*<pre>.*</pre>\s*#s', '', (string) $docBlock->getDescription()));
}

function getSummary($docBlock)
{
    return markdown($docBlock->getSummary()) . "\n";
}

function getExample($docBlock)
{
    $description = (string) $docBlock->getDescription();

    if (preg_match('#<pre>\s*(.*)\s*</pre>#s', $description, $match)) {
        return str_replace('\\/', '/', $match[1]);
    }
}

function getReturn($docBlock)
{
    $tags = $docBlock->getTagsByName('return');

    if (!$tags) {
        return null;
    }

    $tag = $tags[0];

    return [
        'type' => (string) $tag->getType(),
        'description' => markdown((string) $tag->getDescription()),
    ];
}

function getHeader($function, $arguments)
{
    $arguments = array_map(
        function ($arg) {
            $str = '';

            if ($arg['type'] && strpos($arg['type'], '|') === false) {
                $str .= $arg['type'] . ' ';
            }

            if ($arg['variadic']) {
                $str .= '...';
            }

            $str .= '$' . $arg['name'];

            if ($arg['default']) {
                $str .= ' = ' . $arg['default'];
            }

            return $str;
        },
        $arguments
    );

    return $function->getShortName() . '(' . implode(', ', $arguments) . ")\n";
}

$filesystemLoader = new FilesystemLoader(__DIR__.'/views/%name%.php');

$templating = new PhpEngine(new TemplateNameParser(), $filesystemLoader);

$functions = get_defined_functions();

$functions = array_filter(
    array_map(
        function ($name) {
            $function = new ReflectionFunction($name);

            $docBlock = getDocBlock($function);
            if ($docBlock && $docBlock->getTagsByName('nodocs')) {
                return;
            }

            $arguments = getArguments($function, $docBlock);

            $result = [
                'arguments' => $arguments,
                'file' => basename($function->getFilename()),
                'header' => getHeader($function, $arguments),
                'name' => $function->getName(),
                'shortName' => $function->getShortName(),
            ];

            if ($docBlock) {
                $example = getExample($docBlock);

                ob_start();
                eval($example);
                $output = ob_get_contents();
                ob_end_clean();

                $result = array_merge(
                    $result,
                    [
                        'description' => getDescription($docBlock),
                        'example' => $example,
                        'output' => $output,
                        'return' => getReturn($docBlock),
                        'summary' => getSummary($docBlock),
                    ]
                );
            }

            return $result;
        },
        array_filter(
            $functions['user'],
            function ($name) {
                return preg_match('#^datashaman\\\\phpcheck#', $name);
            }
        )
    )
);

usort($functions, function ($a, $b) {
    return $a['shortName'] <=> $b['shortName'];
});

$indexedGists = [];

foreach ($gists as $gist) {
    if (preg_match('#^(Datashaman\\\\PHPCheck\\\\.+) Example$#', $gist['description'], $match)) {
        $indexedGists[$match[1]] = $gist;
    }
}

foreach ($functions as &$function) {
    if (isset($function['example'])) {
        $code = <<<CODE
<?php
<<<CONFIG
packages:
    - "datashaman/phpcheck: dev-wip"
CONFIG;
#
# This is a Melody script. http://melody.sensiolabs.org/
#
{$function['example']}
CODE;

        $description = $function['name'] . ' Example';

        $params = [
            'description' => $description,
            'files' => [
                $description => [
                    'content' => $code,
                ],
            ],
            'public' => true,
        ];

        if (isset($indexedGists[$function['name']])) {
            $gist = $indexedGists[$function['name']];
            $contents = file_get_contents($gist['files'][$description]['raw_url']);

            if ($contents !== $code) {
                $gist = $client->api('gists')->update($gist['id'], $params);
            }
        } else {
            $gist = $client->api('gists')->create($params);
        }

        $function['gist'] = $gist['html_url'];
    }
}

$functions = array_reduce(
    $functions,
    function ($acc, $function) {
        if (!isset($acc[$function['file']])) {
            $acc[$function['file']] = [];
        }

        $acc[$function['file']][] = $function;

        return $acc;
    },
    []
);

echo $templating->render('functions', compact('functions'));