generate_docs.php

<?php

declare(strict_types=1);

require __DIR__ . \DIRECTORY_SEPARATOR . 'vendor' . \DIRECTORY_SEPARATOR . 'autoload.php';

final class DocsGenerator
{
    private const string NAMESPACE_PREFIX = 'Ghostwriter\\PsrPhpunitAssertions';

    /**
     * @throws \Throwable
     */
    public static function generate(string $sourceDirectory, string $outputFile): void
    {
        $traits = self::getTraitClasses($sourceDirectory);

        $markdown = "# Psr Phpunit Assertions Docs\n\n";
        foreach ($traits as $trait) {
            $markdown .= self::generateTraitDocs($trait);
        }
        $markdown .= "\n";

        \file_put_contents($outputFile, $markdown);
    }

    private static function extractClassName(string $file, string $sourceDirectory): string
    {
        return \sprintf('%s\\%s', self::NAMESPACE_PREFIX, \basename(\str_replace($sourceDirectory, '', $file), '.php'));
    }

    private static function formatMethodSignature(\ReflectionMethod $method): string
    {
        $params = \array_map(
            static fn ($param) => \mb_trim(
                ($param->hasType() ? $param->getType() . ' ' : '') . '$' . $param->getName()
            ),
            $method->getParameters()
        );

        return \sprintf(
            'public%s function %s(%s): %s',
            $method->isStatic() ? ' static' : '',
            $method->getName(),
            \implode(', ', $params),
            $method->hasReturnType() ? $method->getReturnType() : 'void'
        );
    }

    /**
     * @throws \Throwable
     */
    private static function generateTraitDocs(string $trait): string
    {
        $reflection = new \ReflectionClass($trait);
        $methods = $reflection->getMethods(\ReflectionMethod::IS_PUBLIC);

        if ([] === $methods) {
            return '';
        }

        $trait = $reflection->getShortName();

        $markdown = \sprintf('## `%s`', $trait);

        $markdown .= \sprintf("\n\n```php\n<?php\ntrait %s {\n", $trait);

        $indent = \str_repeat(' ', 4);
        foreach ($methods as $method) {
            $markdown .= $indent . self::formatMethodSignature($method) . ";\n";
        }

        $markdown .= "}\n```\n\n";

        return $markdown;
    }

    private static function getTraitClasses(string $sourceDirectory): array
    {
        $files = \glob($sourceDirectory . '/*Trait.php');

        $traits = [];

        foreach ($files as $file) {

            $className = self::extractClassName($file, $sourceDirectory);

            if (! \trait_exists($className)) {
                continue;
            }

            $traits[] = $className;
        }

        return $traits;
    }
}

\DocsGenerator::generate(__DIR__ . '/src', __DIR__ . '/docs/README.md');