init

.gitattributes

@@ -0,0 +1,10 @@
+# Path-based git attributes
+# https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
+
+# Ignore all test and documentation with "export-ignore".
+/.gitattributes         export-ignore
+/.gitignore             export-ignore
+/.travis.yml            export-ignore
+/tests                  export-ignore
+/.editorconfig          export-ignore
+.phpunit.result.cache   export-ignore

.gitignore

@@ -0,0 +1,8 @@
+/.idea/
+/vendor
+/composer.phar
+/composer.lock
+/.DS_Store
+/.idea
+/.php_cs.cache
+/.phpunit.result.cache

README.md

@@ -0,0 +1,5 @@
+# Artisan Documentator
+
+## Installation
+
+Run command: `composer require --dev artarts36/artisan-documentator`

composer.json

@@ -0,0 +1,38 @@
+{
+    "name": "artarts36/artisan-documentator",
+    "description": "Laravel Artisan Documentator",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [],
+    "authors": [
+        {
+            "name": "ArtARTs36",
+            "email": "temicska99@mail.ru"
+        }
+    ],
+    "minimum-stability": "dev",
+    "prefer-stable":true,
+    "require": {
+        "illuminate/config": "^8.0",
+        "illuminate/console": "^8.0",
+        "illuminate/filesystem": "^8.69",
+        "illuminate/support": "^8.0"
+    },
+    "require-dev": {
+        "squizlabs/php_codesniffer": "*"
+    },
+    "autoload": {
+        "psr-4": {
+            "ArtARTs36\\ArtisanDocumentator\\": "src/"
+        }
+    },
+    "config": {
+        "preferred-install": "dist",
+        "sort-packages": true
+    },
+    "scripts": {
+        "lint": [
+            "./vendor/bin/phpcs --standard=PSR2 src/"
+        ]
+    }
+}

config/artisan_documentator.php

@@ -0,0 +1,19 @@
+<?php
+
+use ArtARTs36\ArtisanDocumentator\Documentators\TemplateDocumentator;
+
+return [
+    'documentators' => [
+        'default' => 'template',
+        'drivers' => [
+            'template' => [
+                'class' => TemplateDocumentator::class,
+                'view' => 'artisan_documentator::command_doc_markdown',
+            ],
+        ],
+    ],
+    'namespaces' => [
+        //'app:' => 'App Commands',
+        //'make:' => 'Laravel make Commands',
+    ],
+];

resources/views/command_doc_markdown.blade.php

@@ -0,0 +1,11 @@
+# Console Commands
+
+@foreach($groups as $group)
+## {{ $group['name'] }}
+
+|  Command |  Description | Signature  |
+| ------------ | ------------ | ------------ |
+@foreach($group['commands'] as $command)
+    |  {{ $command['name'] }} | {{ $command['description'] }}  | {!! str_replace(['|', "\n"], ['&#124;', '<br>'], $command['signature']) !!}  |
+@endforeach
+@endforeach

src/Contexts/DocGenerateContext.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Contexts;
+
+class DocGenerateContext
+{
+    /**
+     * @param array<string, string> $namespacesGroups
+     */
+    public function __construct(
+        public array $namespacesGroups,
+    ) {
+        //
+    }
+
+    public function getNamespaces(): array
+    {
+        return array_keys($this->namespacesGroups);
+    }
+}

src/Contracts/ArtisanDocumentator.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Contracts;
+
+use Symfony\Component\Console\Command\Command;
+
+interface ArtisanDocumentator
+{
+    /**
+     * @param array<string, array<Command>> $commands
+     * @param array<string, string> $namespaceGroups
+     */
+    public function generate(array $commands, array $namespaceGroups): string;
+}

src/Contracts/CommandsFetcher.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Contracts;
+
+use Illuminate\Console\Command;
+
+interface CommandsFetcher
+{
+    /**
+     * @return array<string, array<Command>>
+     */
+    public function fetch(array $namespaces = []): array;
+}

src/Documentators/ConfigDocumentatorFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Documentators;
+
+use ArtARTs36\ArtisanDocumentator\Contracts\ArtisanDocumentator;
+use Illuminate\Contracts\Container\Container;
+
+class ConfigDocumentatorFactory
+{
+    /**
+     * @param array<string, class-string<ArtisanDocumentator>> $classMap
+     */
+    public function __construct(private Container $container, private array $classMap)
+    {
+        //
+    }
+
+    public function create(string $type): ArtisanDocumentator
+    {
+        return $this->container->make(
+            $this->classMap[$type] ?? throw new \RuntimeException('ArtisanDocumentator not found!')
+        );
+    }
+}

src/Documentators/SignatureBuilder.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Documentators;
+
+use Symfony\Component\Console\Command\Command;
+
+class SignatureBuilder
+{
+    public function build(Command $command): string
+    {
+        $signature = $command->getName() ?? '';
+
+        foreach ($command->getDefinition()->getArguments() as $argument) {
+            $signature .= ' {' . $argument->getName() . '}';
+        }
+
+        foreach ($command->getDefinition()->getOptions() as $option) {
+            $signature .= ' {--' . $option->getName();
+
+            if ($option->acceptValue()) {
+                $signature .= ' =';
+            }
+
+            if (! empty($option->getDescription())) {
+                $signature .= ': ' . $option->getDescription();
+            }
+
+            $signature .= "}\n";
+        }
+
+        return $signature;
+    }
+}

src/Documentators/TemplateDocumentator.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Documentators;
+
+use ArtARTs36\ArtisanDocumentator\Contracts\ArtisanDocumentator;
+use Illuminate\Console\Command;
+use Illuminate\Contracts\View\Factory;
+
+class TemplateDocumentator implements ArtisanDocumentator
+{
+    public function __construct(
+        private Factory $viewer,
+        private SignatureBuilder $signature,
+        private string $template,
+    ) {
+        //
+    }
+
+    public function generate(array $commands, array $namespaceGroups): string
+    {
+        $prepared = [];
+
+        foreach ($commands as $namespace => $cmd) {
+            $prepared[$namespace]['name'] = $namespaceGroups[$namespace] ?? 'All Commands';
+
+            /** @var Command $command */
+            foreach ($cmd as $command) {
+                $prepared[$namespace]['commands'][] = [
+                    'name' => $command->getName(),
+                    'description' => $command->getDescription(),
+                    'signature' => $this->signature->build($command),
+                ];
+            }
+        }
+
+        return $this->viewer->make($this->template, [
+            'groups' => $prepared,
+        ])->render();
+    }
+}

src/Fetchers/AppCommandsFetcher.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Fetchers;
+
+use ArtARTs36\ArtisanDocumentator\Contracts\CommandsFetcher;
+use Illuminate\Contracts\Console\Kernel;
+use Illuminate\Support\Arr;
+use Illuminate\Console\Application;
+use Symfony\Component\Console\Command\Command;
+
+class AppCommandsFetcher implements CommandsFetcher
+{
+    public function __construct(private Kernel $application)
+    {
+        //
+    }
+
+    public function fetch(array $namespaces = []): array
+    {
+        if (count($namespaces) === 0) {
+            return ['all' => $this->application->all()];
+        }
+
+        return $this->filterCommands($namespaces);
+    }
+
+    /**
+     * @param array<string> $namespaces
+     * @return array<string, array<Command>>
+     */
+    protected function filterCommands(array $namespaces): array
+    {
+        $commands = [];
+
+        foreach ($this->application->all() as $command) {
+            foreach ($namespaces as $namespace) {
+                if (str_starts_with($command->getName(), $namespace)) {
+                    $commands[$namespace][$command->getName()] = $command;
+
+                    break;
+                }
+            }
+        }
+
+        return $commands;
+    }
+}

src/Generators/DocGenerator.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Generators;
+
+use ArtARTs36\ArtisanDocumentator\Contexts\DocGenerateContext;
+use ArtARTs36\ArtisanDocumentator\Contracts\CommandsFetcher;
+use ArtARTs36\ArtisanDocumentator\Documentators\ConfigDocumentatorFactory;
+use Illuminate\Filesystem\Filesystem;
+
+class DocGenerator
+{
+    public function __construct(
+        private ConfigDocumentatorFactory $documentators,
+        private CommandsFetcher $commands,
+        private DocGenerateContext $context,
+        private Filesystem $files,
+    ) {
+    }
+
+    public function generate(string $documentator, string $path): void
+    {
+        $content = $this
+            ->documentators
+            ->create($documentator)
+            ->generate($this->commands->fetch($this->context->getNamespaces()), $this->context->namespacesGroups);
+
+        $this->files->put($path, $content);
+    }
+}

src/Ports/Console/GenerateDocCommand.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace ArtARTs36\ArtisanDocumentator\Ports\Console;
+
+use ArtARTs36\ArtisanDocumentator\Generators\DocGenerator;
+use Illuminate\Console\Command;
+use Illuminate\Contracts\Config\Repository;
+
+class GenerateDocCommand extends Command
+{
+    protected $signature = 'command:doc {path} {--documentator=}';
+
+    protected $description = 'Generate commands documentation';
+
+    public function handle(DocGenerator $generator, Repository $config)
+    {
+        $generator->generate(
+            $this->option('documentator') ?? $config->get('artisan_documentator.documentators.default'),
+            $this->argument('path')
+        );
+    }
+}