From cd2e4d07cbdf7a54c18304c7a66aeb84f6c638a4 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Wed, 27 Nov 2024 11:03:22 +0400 Subject: [PATCH 1/4] refactor(documentator)!: `include:document-list` instruction template will use object instead of array. --- .../views/document-list/default.blade.php | 12 ++++++------ .../documentator/docs/Commands/preprocess.md | 6 +++++- .../IncludeDocumentList/Instruction.php | 19 ++++++++++--------- .../IncludeDocumentList/Parameters.php | 6 +++++- .../IncludeDocumentList/Template/Data.php | 14 ++++++++++++++ .../IncludeDocumentList/Template/Document.php | 15 +++++++++++++++ 6 files changed, 55 insertions(+), 17 deletions(-) create mode 100644 packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php create mode 100644 packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Document.php diff --git a/packages/documentator/defaults/views/document-list/default.blade.php b/packages/documentator/defaults/views/document-list/default.blade.php index b3f1dca44..bcf5d7ada 100644 --- a/packages/documentator/defaults/views/document-list/default.blade.php +++ b/packages/documentator/defaults/views/document-list/default.blade.php @@ -1,17 +1,17 @@ $documents + * @var \LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data $data */ ?> -@foreach ($documents as $document) -## {!! $document['title'] !!} -@if($document['summary']) +@foreach ($data->documents as $document) +## {!! $document->title !!} +@if($document->summary) -{!! $document['summary'] !!} +{!! $document->summary !!} @endif -[Read more](<{{ $document['path'] }}>). +[Read more](<{{ $document->path }}>). @if (!$loop->last) @endif diff --git a/packages/documentator/docs/Commands/preprocess.md b/packages/documentator/docs/Commands/preprocess.md index 1fdaca177..81c24424e 100644 --- a/packages/documentator/docs/Commands/preprocess.md +++ b/packages/documentator/docs/Commands/preprocess.md @@ -72,7 +72,8 @@ which will be replaced to FQCN (if possible). Other tags are ignored. * `` - additional parameters * `depth`: `array|string|int|null` = `0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth) (eg the `0` means no nested directories, the `null` removes limits). - * `template`: `string` = `'default'` - Blade template. + * `template`: `string` = `'default'` - Blade template. The documents passed in the `$data` ([`Data`][code-links/84d51020d324cc16]) + variable. Also, be careful with leading whitespaces. * `order`: [`SortOrder`][code-links/7e5c66e8748c6ff8] = [`SortOrder::Asc`][code-links/08e0648f66e2d1a5] - Sort order. Returns the list of `*.md` files in the `` directory. Each file @@ -164,6 +165,9 @@ Glob(s) to exclude. [//]: # (start: code-links) [//]: # (warning: Generated automatically. Do not edit.) +[code-links/84d51020d324cc16]: ../../src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php + "\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data" + [code-links/f9077a28b352f84b]: ../../src/Processor/Tasks/Preprocess/Instructions/IncludeExample/Contracts/Runner.php "\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExample\Contracts\Runner" diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php index 9f0ec0c5b..074d2e414 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php @@ -12,6 +12,8 @@ use LastDragon_ru\LaraASP\Documentator\Processor\Metadata\Markdown; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction as InstructionContract; +use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data as TemplateData; +use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Document as TemplateDocument; use LastDragon_ru\LaraASP\Documentator\Utils\Sorter; use LastDragon_ru\LaraASP\Documentator\Utils\Text; use Override; @@ -54,7 +56,6 @@ public static function getParameters(): string { */ #[Override] public function __invoke(Context $context, string $target, mixed $parameters): Generator { - /** @var list $documents */ $documents = []; $iterator = Cast::to(Iterator::class, yield new FileIterator($target, '*.md', $parameters->depth)); $self = $context->file->getPath(); @@ -77,11 +78,11 @@ public function __invoke(Context $context, string $target, mixed $parameters): G // Add $document = $context->toSplittable($document); - $documents[] = [ - 'path' => $context->file->getRelativePath($file), - 'title' => $document->getTitle() ?? Text::getPathTitle($file->getName()), - 'summary' => $document->getSummary(), - ]; + $documents[] = new TemplateDocument( + $context->file->getRelativePath($file), + $document->getTitle() ?? Text::getPathTitle($file->getName()), + $document->getSummary(), + ); } // Empty? @@ -92,14 +93,14 @@ public function __invoke(Context $context, string $target, mixed $parameters): G // Sort $comparator = $this->sorter->forString($parameters->order); - usort($documents, static function (array $a, $b) use ($comparator): int { - return $comparator($a['title'], $b['title']); + usort($documents, static function ($a, $b) use ($comparator): int { + return $comparator($a->title, $b->title); }); // Render $template = "document-list.{$parameters->template}"; $list = $this->viewer->render($template, [ - 'documents' => $documents, + 'data' => new TemplateData($documents), ]); // Return diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php index c9662bfc6..441e30dc8 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php @@ -3,6 +3,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Parameters as ParametersContract; +use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data; use LastDragon_ru\LaraASP\Documentator\Utils\SortOrder; use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; use Symfony\Component\Finder\Finder; @@ -22,7 +23,10 @@ public function __construct( */ public readonly array|string|int|null $depth = 0, /** - * Blade template. + * Blade template. The documents passed in the `$data` ({@see Data}) + * variable. Also, be careful with leading whitespaces. + * + * @see Data */ public readonly string $template = 'default', /** diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php new file mode 100644 index 000000000..863ca5ea6 --- /dev/null +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php @@ -0,0 +1,14 @@ + + */ + public array $documents, + ) { + // empty + } +} diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Document.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Document.php new file mode 100644 index 000000000..bbe68b780 --- /dev/null +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Document.php @@ -0,0 +1,15 @@ + Date: Wed, 27 Nov 2024 11:51:11 +0400 Subject: [PATCH 2/4] refactor(documentator)!: `\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context` will contain `\LastDragon_ru\LaraASP\Documentator\Markdown\Document` and `\LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block` instead of `$target` and `$parameters`. --- .../src/Processor/Tasks/Preprocess/Context.php | 5 +++-- .../Exceptions/ArtisanCommandError.php | 2 +- .../Exceptions/ArtisanCommandFailed.php | 2 +- .../IncludeArtisan/InstructionTest.php | 16 ++++++++++++---- .../Exceptions/TargetIsNotValidPhpFile.php | 2 +- .../IncludeDocBlock/InstructionTest.php | 3 ++- .../IncludeDocumentList/InstructionTest.php | 8 +++++--- .../IncludeExample/InstructionTest.php | 6 ++++-- .../IncludeExec/Exceptions/TargetExecFailed.php | 2 +- .../IncludeExec/InstructionTest.php | 4 +++- .../IncludeFile/InstructionTest.php | 3 ++- .../Exceptions/TargetIsNotDirective.php | 2 +- .../IncludeGraphqlDirective/InstructionTest.php | 10 ++++++---- .../IncludePackageList/InstructionTest.php | 8 +++++--- .../IncludeTemplate/InstructionTest.php | 9 +++++---- .../src/Processor/Tasks/Preprocess/Task.php | 4 +--- .../src/Processor/Tasks/Preprocess/TaskTest.php | 17 ----------------- 17 files changed, 53 insertions(+), 50 deletions(-) diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Context.php b/packages/documentator/src/Processor/Tasks/Preprocess/Context.php index 6ec79813f..38349d489 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Context.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Context.php @@ -13,6 +13,7 @@ use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesInline; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesPrefix; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\SelfLinksRemove; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; @@ -20,8 +21,8 @@ class Context { public function __construct( public readonly Directory $root, public readonly File $file, - public readonly string $target, - public readonly ?string $parameters, + public readonly Document $document, + public readonly Block $node, private readonly Mutation $mutation, ) { // empty diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandError.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandError.php index 3754d2270..8b3153e91 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandError.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandError.php @@ -17,7 +17,7 @@ public function __construct( $context, sprintf( 'Artisan command `%s` failed (in `%s`).', - $context->target, + $context->node->getDestination(), $context->root->getRelativePath($context->file), ), $previous, diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandFailed.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandFailed.php index a5dca2c59..eaa6478ff 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandFailed.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandFailed.php @@ -18,7 +18,7 @@ public function __construct( $context, sprintf( 'Artisan command `%s` exited with status code `%s` (in `%s`).', - $context->target, + $context->node->getDestination(), $this->result, $context->root->getRelativePath($context->file), ), diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/InstructionTest.php index d47900d9d..07a376d2a 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/InstructionTest.php @@ -8,7 +8,9 @@ use LastDragon_ru\LaraASP\Core\Application\ApplicationResolver; use LastDragon_ru\LaraASP\Core\Path\DirectoryPath; use LastDragon_ru\LaraASP\Core\Path\FilePath; +use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -36,7 +38,7 @@ public function testInvoke(): void { $params = new Parameters('...'); $expected = 'result'; $command = 'command to execute'; - $context = new Context($root, $file, $command, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $this->override(Kernel::class, static function (MockInterface $mock) use ($command, $expected): void { @@ -82,9 +84,15 @@ static function (InputInterface $input, OutputInterface $output) use ($expected) public function testInvokeFailed(): void { $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false); $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); + $node = new class() extends Block { + #[Override] + public function getDestination(): string { + return 'command to execute'; + } + }; $params = new Parameters('...'); - $command = 'command to execute'; - $context = new Context($root, $file, $command, '{...}', new Nop()); + $command = $node->getDestination(); + $context = new Context($root, $file, new Document(''), $node, new Nop()); $instance = $this->app()->make(Instruction::class); $this->override(Kernel::class, static function (MockInterface $mock) use ($command): void { @@ -140,7 +148,7 @@ public function testGetCommand(): void { $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...'); $command = 'artisan:command $directory {$directory} "{$directory}" $file {$file} "{$file}"'; - $context = new Context($root, $file, $command, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = new class (Mockery::mock(ApplicationResolver::class)) extends Instruction { #[Override] public function getCommand(Context $context, string $target, Parameters $parameters): string { diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Exceptions/TargetIsNotValidPhpFile.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Exceptions/TargetIsNotValidPhpFile.php index 9447ddb23..769f557b5 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Exceptions/TargetIsNotValidPhpFile.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Exceptions/TargetIsNotValidPhpFile.php @@ -14,7 +14,7 @@ public function __construct(Context $context, ?Throwable $previous = null) { $context, sprintf( 'The `%s` is not a valid PHP file (in `%s`).', - $context->target, + $context->node->getDestination(), $context->root->getRelativePath($context->file), ), $previous, diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest.php index 6de200895..fe7189da1 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest.php @@ -7,6 +7,7 @@ use LastDragon_ru\LaraASP\Core\Path\FilePath; use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -34,7 +35,7 @@ public function testInvoke(Closure|string $expected, string $file, Parameters $p $root = new Directory($path->getDirectoryPath(), false); $file = new File($path, false); $target = $file->getName(); - $context = new Context($root, $file, $target, null, new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); if ($expected instanceof Closure) { diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php index c6867b6aa..1a7e6689f 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php @@ -3,7 +3,9 @@ namespace LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList; use LastDragon_ru\LaraASP\Core\Path\FilePath; +use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -25,7 +27,7 @@ public function testInvokeSameDirectory(): void { $file = new File($path, false); $params = new Parameters('...'); $target = './'; - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); @@ -45,7 +47,7 @@ public function testInvokeAnotherDirectory(): void { $file = new File($path, false); $params = new Parameters('...'); $target = basename(self::getTestData()->path('/')); - $context = new Context($root, $file, $target, '', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); @@ -66,7 +68,7 @@ public function testInvokeNestedDirectories(): void { $file = new File($path, false); $params = new Parameters('...', null, order: SortOrder::Desc); $target = './'; - $context = new Context($root, $file, $target, '', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/InstructionTest.php index 045b1e027..6492ad029 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/InstructionTest.php @@ -3,7 +3,9 @@ namespace LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExample; use LastDragon_ru\LaraASP\Core\Path\FilePath; +use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -32,7 +34,7 @@ public function testInvoke(string $expected, string $output): void { $file = new File($path, false); $params = new Parameters('...'); $target = self::getTestData()->path('Example.md'); - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $this->override(Runner::class, static function (MockInterface $mock) use ($target, $output): void { $mock @@ -58,7 +60,7 @@ public function testInvokeNoRun(): void { $file = new File($path, false); $params = new Parameters('...'); $target = $file->getName(); - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $expected = trim($file->getContent()); $instance = $this->app()->make(Instruction::class); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/Exceptions/TargetExecFailed.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/Exceptions/TargetExecFailed.php index f93f13488..e93c7be36 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/Exceptions/TargetExecFailed.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/Exceptions/TargetExecFailed.php @@ -14,7 +14,7 @@ public function __construct(Context $context, ?Throwable $previous = null) { $context, sprintf( 'Failed to execute the `%s` command (in `%s`).', - $context->target, + $context->node->getDestination(), $context->root->getRelativePath($context->file), ), $previous, diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/InstructionTest.php index 962fdbdc2..d80a66345 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExec/InstructionTest.php @@ -6,7 +6,9 @@ use Illuminate\Process\PendingProcess; use LastDragon_ru\LaraASP\Core\Path\DirectoryPath; use LastDragon_ru\LaraASP\Core\Path\FilePath; +use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -25,7 +27,7 @@ public function testInvoke(): void { $params = new Parameters('...'); $expected = 'result'; $command = 'command to execute'; - $context = new Context($root, $file, $command, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $factory = $this->override(Factory::class, function () use ($command, $expected): Factory { $factory = $this->app()->make(Factory::class); $factory->preventStrayProcesses(); diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeFile/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeFile/InstructionTest.php index 4d4a9d064..35ad12482 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeFile/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeFile/InstructionTest.php @@ -6,6 +6,7 @@ use LastDragon_ru\LaraASP\Core\Path\FilePath; use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -31,7 +32,7 @@ public function testInvoke(string $expected, string $source): void { $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...'); $target = self::getTestData()->path($source); - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $expected = self::getTestData()->content($expected); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/Exceptions/TargetIsNotDirective.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/Exceptions/TargetIsNotDirective.php index 6c868d897..b2e92336e 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/Exceptions/TargetIsNotDirective.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/Exceptions/TargetIsNotDirective.php @@ -14,7 +14,7 @@ public function __construct(Context $context, ?Throwable $previous = null) { $context, sprintf( 'The `%s` is not a directive (in `%s`).', - $context->target, + $context->node->getDestination(), $context->root->getRelativePath($context->file), ), $previous, diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/InstructionTest.php index 318ac7de6..368c0a344 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeGraphqlDirective/InstructionTest.php @@ -6,7 +6,9 @@ use GraphQL\Language\Parser; use LastDragon_ru\LaraASP\Core\Path\DirectoryPath; use LastDragon_ru\LaraASP\Core\Path\FilePath; +use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -52,7 +54,7 @@ public function testInvoke(): void { $file = Mockery::mock(File::class); $params = new Parameters('...'); $target = '@test'; - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); @@ -79,7 +81,7 @@ public function testInvokeNoPrinter(): void { $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...'); $target = '@test'; - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -107,7 +109,7 @@ public function testInvokeNoDirective(): void { $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...'); $target = '@test'; - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -126,7 +128,7 @@ public function testInvokeNoDirectiveResolver(): void { $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...'); $target = '@test'; - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludePackageList/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludePackageList/InstructionTest.php index 7936fca66..5218ac10c 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludePackageList/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludePackageList/InstructionTest.php @@ -3,7 +3,9 @@ namespace LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludePackageList; use LastDragon_ru\LaraASP\Core\Path\FilePath; +use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\Dependencies\FileReference; use LastDragon_ru\LaraASP\Documentator\Processor\Exceptions\DependencyNotFound; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; @@ -31,7 +33,7 @@ public function testInvoke(string $expected, string $template, SortOrder $order) $file = new File($path, false); $target = $root->getDirectoryPath('packages'); $params = new Parameters('...', template: $template, order: $order); - $context = new Context($root, $file, (string) $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); @@ -52,7 +54,7 @@ public function testInvokeNoReadme(): void { $file = new File($path, false); $target = $root->getDirectoryPath('no readme'); $params = new Parameters('...'); - $context = new Context($root, $file, (string) $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $package = $fs->getDirectory(new Directory($target, false), 'package'); @@ -71,7 +73,7 @@ public function testInvokeEmptyReadme(): void { $file = new File($path, false); $target = $root->getDirectoryPath('empty readme'); $params = new Parameters('...'); - $context = new Context($root, $file, (string) $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $package = $fs->getDirectory(new Directory($target, false), 'package'); $expected = $fs->getFile($root, 'empty readme/package/README.md'); diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeTemplate/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeTemplate/InstructionTest.php index f8a4a2d2b..559762825 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeTemplate/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeTemplate/InstructionTest.php @@ -6,6 +6,7 @@ use LastDragon_ru\LaraASP\Core\Path\FilePath; use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; @@ -37,7 +38,7 @@ public function testInvoke(string $expected, string $source, array $data): void $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...', $data); $target = self::getTestData()->path($source); - $context = new Context($root, $file, $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); $expected = self::getTestData()->content($expected); $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); @@ -56,7 +57,7 @@ public function testInvokeNoData(): void { $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false); $params = new Parameters('...', []); $target = $file->getPath(); - $context = new Context($root, $file, (string) $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -77,7 +78,7 @@ public function testInvokeVariablesUnused(): void { 'd' => 'D', ]); $target = $file->getPath(); - $context = new Context($root, $file, (string) $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -95,7 +96,7 @@ public function testInvokeVariablesMissed(): void { 'a' => 'A', ]); $target = $file->getPath(); - $context = new Context($root, $file, (string) $target, '{...}', new Nop()); + $context = new Context($root, $file, new Document(''), new Block(), new Nop()); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Task.php b/packages/documentator/src/Processor/Tasks/Preprocess/Task.php index 9dfe5e50e..32474ec37 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Task.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Task.php @@ -235,9 +235,7 @@ protected function parse(Directory $root, File $file, Document $document): array } // Parse - $title = $node->getTitle(); - $title = $title !== '' ? $title : null; - $context = new Context($root, $file, $node->getDestination(), $title, $mutation); + $context = new Context($root, $file, $document, $node, $mutation); $parameters = $instruction::getParameters(); $parameters = $this->serializer->deserialize($parameters, $params, 'json'); diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/TaskTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/TaskTest.php index f3bfb3a3b..b2ef7724b 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/TaskTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/TaskTest.php @@ -4,17 +4,14 @@ use LastDragon_ru\LaraASP\Core\Application\ContainerResolver; use LastDragon_ru\LaraASP\Core\Path\FilePath; -use LastDragon_ru\LaraASP\Core\Utils\Cast; use LastDragon_ru\LaraASP\Documentator\Markdown\Document; use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Location; use LastDragon_ru\LaraASP\Documentator\Markdown\Utils; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory; use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File; -use LastDragon_ru\LaraASP\Documentator\Processor\InstanceList; use LastDragon_ru\LaraASP\Documentator\Processor\Metadata\Markdown; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction; use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Parameters; -use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Mutations\InstructionsRemove; use LastDragon_ru\LaraASP\Documentator\Testing\Package\ProcessorHelper; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; @@ -22,7 +19,6 @@ use Mockery; use Override; use PHPUnit\Framework\Attributes\CoversClass; -use ReflectionProperty; use function array_map; use function json_encode; @@ -93,9 +89,6 @@ public function parse(Directory $root, File $file, Document $document): array { $root = Mockery::mock(Directory::class); $file = Mockery::mock(File::class); - $mutation = new InstructionsRemove( - Cast::to(InstanceList::class, (new ReflectionProperty(Task::class, 'instructions'))->getValue($task)), - ); $document = new Document(self::MARKDOWN); $tokens = $task->parse($root, $file, $document); $actual = array_map( @@ -106,7 +99,6 @@ static function (Token $token): array { return [ $token->instruction, - $token->context, $token->target, $token->parameters, $nodes, @@ -123,7 +115,6 @@ static function (Token $token): array { 0 => [ 'bb30809c6ca4c80a' => [ $b, - new Context($root, $file, './path/to/file', null, $mutation), './path/to/file', new TaskTest__Parameters('./path/to/file'), [ @@ -136,13 +127,6 @@ static function (Token $token): array { ], 'f5f55887ee415b3d' => [ $b, - new Context( - $root, - $file, - './path/to/file/parametrized', - '{"a": "aa", "b": {"a": "a", "b": "b"}}', - $mutation, - ), './path/to/file/parametrized', new TaskTest__Parameters( './path/to/file/parametrized', @@ -161,7 +145,6 @@ static function (Token $token): array { PHP_INT_MAX => [ '4f76e5da6e5aabbc' => [ $a, - new Context($root, $file, './path/to/file%20%22value%22', null, $mutation), './path/to/file "value"', new TaskTest__ParametersEmpty('./path/to/file "value"'), [ From defdfc1e7f170ef4fd080abbd457b8603973f3d8 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Wed, 27 Nov 2024 16:24:34 +0400 Subject: [PATCH 3/4] feat(documentator): Added ability to specify headings `level` for `include:document-list` instruction. --- .../views/document-list/default.blade.php | 2 +- .../documentator/docs/Commands/preprocess.md | 5 + .../IncludeDocumentList/Instruction.php | 37 ++- .../IncludeDocumentList/InstructionTest.php | 232 ++++++++++++++---- .../InstructionTest~AnotherDirectory.md | 19 -- .../InstructionTest~NestedDirectories.md | 19 -- .../InstructionTest~SameDirectory.md | 13 - .../IncludeDocumentList/Parameters.php | 8 + .../IncludeDocumentList/Template/Data.php | 4 + 9 files changed, 235 insertions(+), 104 deletions(-) delete mode 100644 packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~AnotherDirectory.md delete mode 100644 packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~NestedDirectories.md delete mode 100644 packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~SameDirectory.md diff --git a/packages/documentator/defaults/views/document-list/default.blade.php b/packages/documentator/defaults/views/document-list/default.blade.php index bcf5d7ada..aff85a106 100644 --- a/packages/documentator/defaults/views/document-list/default.blade.php +++ b/packages/documentator/defaults/views/document-list/default.blade.php @@ -5,7 +5,7 @@ ?> @foreach ($data->documents as $document) -## {!! $document->title !!} +{{ str_repeat('#', $data->level) }} {!! $document->title !!} @if($document->summary) {!! $document->summary !!} diff --git a/packages/documentator/docs/Commands/preprocess.md b/packages/documentator/docs/Commands/preprocess.md index 81c24424e..f5cba05c7 100644 --- a/packages/documentator/docs/Commands/preprocess.md +++ b/packages/documentator/docs/Commands/preprocess.md @@ -75,6 +75,11 @@ which will be replaced to FQCN (if possible). Other tags are ignored. * `template`: `string` = `'default'` - Blade template. The documents passed in the `$data` ([`Data`][code-links/84d51020d324cc16]) variable. Also, be careful with leading whitespaces. * `order`: [`SortOrder`][code-links/7e5c66e8748c6ff8] = [`SortOrder::Asc`][code-links/08e0648f66e2d1a5] - Sort order. + * `level`: `?int` = `null` - Headings level. Possible values are + + * `null`: ` + 1` + * `int`: explicit level (`1-6`) + * `0`: `` Returns the list of `*.md` files in the `` directory. Each file must have `# Header` as the first construction. The first paragraph diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php index 074d2e414..e240ca860 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php @@ -5,6 +5,7 @@ use Generator; use Iterator; use LastDragon_ru\LaraASP\Core\Utils\Cast; +use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block; use LastDragon_ru\LaraASP\Documentator\PackageViewer; use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Dependency; use LastDragon_ru\LaraASP\Documentator\Processor\Dependencies\FileIterator; @@ -16,8 +17,11 @@ use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Document as TemplateDocument; use LastDragon_ru\LaraASP\Documentator\Utils\Sorter; use LastDragon_ru\LaraASP\Documentator\Utils\Text; +use League\CommonMark\Extension\CommonMark\Node\Block\Heading; use Override; +use function max; +use function min; use function usort; /** @@ -99,11 +103,42 @@ public function __invoke(Context $context, string $target, mixed $parameters): G // Render $template = "document-list.{$parameters->template}"; + $level = $this->getLevel($context->node, $parameters); $list = $this->viewer->render($template, [ - 'data' => new TemplateData($documents), + 'data' => new TemplateData($documents, $level), ]); // Return return $list; } + + /** + * @return int<1,6> + */ + private function getLevel(Block $node, Parameters $parameters): int { + $level = match ($parameters->level) { + 0 => $this->getNodeLevel($node), + null => $this->getNodeLevel($node) + 1, + default => $parameters->level, + }; + $level = min($level, 6); + $level = max($level, 1); + + return $level; + } + + private function getNodeLevel(Block $block): int { + $level = 0; + + do { + $block = $block->previous(); + + if ($block instanceof Heading) { + $level = $block->getLevel(); + $block = null; + } + } while ($block); + + return $level; + } } diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php index 1a7e6689f..d95393864 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php @@ -11,74 +11,204 @@ use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context; use LastDragon_ru\LaraASP\Documentator\Testing\Package\ProcessorHelper; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; -use LastDragon_ru\LaraASP\Documentator\Utils\SortOrder; +use LastDragon_ru\LaraASP\Serializer\Contracts\Serializer; +use League\CommonMark\Node\Query; use PHPUnit\Framework\Attributes\CoversClass; +use PHPUnit\Framework\Attributes\DataProvider; -use function basename; +use function json_decode; +use function json_encode; + +use const JSON_THROW_ON_ERROR; /** * @internal */ #[CoversClass(Instruction::class)] final class InstructionTest extends TestCase { - public function testInvokeSameDirectory(): void { - $path = (new FilePath(self::getTestData()->path('Document.md')))->getNormalizedPath(); - $root = new Directory($path->getDirectoryPath(), false); - $file = new File($path, false); - $params = new Parameters('...'); - $target = './'; - $context = new Context($root, $file, new Document(''), new Block(), new Nop()); - $instance = $this->app()->make(Instruction::class); - $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); + // + // ========================================================================= + #[DataProvider('dataProviderInvoke')] + public function testInvoke(string $expected, string $path, string $content): void { + // Prepare + $path = (new FilePath(self::getTestData()->path($path)))->getNormalizedPath(); + $root = new Directory($path->getDirectoryPath(), false); + $file = new File($path, false); + $document = new Document($content, $path); + $instruction = (new Query())->where(Query::type(Block::class))->findOne($document->getNode()); - self::assertEquals( - self::getTestData()->content('~SameDirectory.md'), - << + self::assertInstanceOf(Block::class, $instruction); - {$actual} - MARKDOWN, - ); + // Parameters + $target = $instruction->getDestination(); + $parameters = $instruction->getTitle(); + $parameters = $parameters !== '' + ? (array) json_decode($parameters, true, flags: JSON_THROW_ON_ERROR) + : []; + $parameters['target'] = $target; + $parameters = json_encode($parameters, JSON_THROW_ON_ERROR); + $parameters = $this->app()->make(Serializer::class)->deserialize(Parameters::class, $parameters); + + // Test + $context = new Context($root, $file, $document, $instruction, new Nop()); + $instance = $this->app()->make(Instruction::class); + $actual = ProcessorHelper::runInstruction($instance, $context, $target, $parameters); + + self::assertEquals($expected, $actual); } + // + // + // ========================================================================= + /** + * @return array + */ + public static function dataProviderInvoke(): array { + return [ + 'Same Directory / Default parameters' => [ + <<<'MARKDOWN' + # `<` Document B `>` - public function testInvokeAnotherDirectory(): void { - $path = (new FilePath(self::getTestData()->path('~AnotherDirectory.md')))->getNormalizedPath(); - $root = new Directory($path->getDirectoryPath(), false); - $file = new File($path, false); - $params = new Parameters('...'); - $target = basename(self::getTestData()->path('/')); - $context = new Context($root, $file, new Document(''), new Block(), new Nop()); + Summary text. - $instance = $this->app()->make(Instruction::class); - $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); + [Read more](). - self::assertEquals( - self::getTestData()->content('~AnotherDirectory.md'), - << + # Document A - {$actual} - MARKDOWN, - ); - } + Summary text with special characters `<`, `>`, `&`. - public function testInvokeNestedDirectories(): void { - $path = (new FilePath(self::getTestData()->path('nested/Document.md')))->getNormalizedPath(); - $root = new Directory($path->getDirectoryPath(), false); - $file = new File($path, false); - $params = new Parameters('...', null, order: SortOrder::Desc); - $target = './'; - $context = new Context($root, $file, new Document(''), new Block(), new Nop()); - $instance = $this->app()->make(Instruction::class); - $actual = ProcessorHelper::runInstruction($instance, $context, $target, $params); + [Read more](). + + MARKDOWN, + 'Document.md', + <<<'MARKDOWN' + [include:document-list]: ./ + MARKDOWN, + ], + 'Another Directory / Default parameters' => [ + <<<'MARKDOWN' + # `<` Document B `>` + + Summary text. + + [Read more](). + + # Document + + Document summary. + + [Read more](). + + # Document A + + Summary text with special characters `<`, `>`, `&`. + + [Read more](). + + MARKDOWN, + '.php', + <<<'MARKDOWN' + [include:document-list]: ./InstructionTest + MARKDOWN, + ], + 'Nested Directories' => [ + <<<'MARKDOWN' + # Nested B + + Summary [text](../Document.md). + + [Read more](). + + # Nested A + + Summary [text](../Document.md). + + [Read more](). + + # Document C + + Summary [text](../Document.md) summary [link](../Document.md "title") and summary and self and self. + + [Read more](). + + MARKDOWN, + 'nested/Document.md', + <<<'MARKDOWN' + [include:document-list]: . ({"depth": null, "order": "Desc"}) + MARKDOWN, + ], + 'Level `null`' => [ + <<<'MARKDOWN' + ## `<` Document B `>` + + Summary text. + + [Read more](). + + ## Document A + + Summary text with special characters `<`, `>`, `&`. + + [Read more](). + + MARKDOWN, + 'Document.md', + <<<'MARKDOWN' + # Header + + Text text. + + [include:document-list]: ./ ({"level": null}) + MARKDOWN, + ], + 'Level `0`' => [ + <<<'MARKDOWN' + ### `<` Document B `>` + + Summary text. + + [Read more](). + + ### Document A + + Summary text with special characters `<`, `>`, `&`. + + [Read more](). + + MARKDOWN, + 'Document.md', + <<<'MARKDOWN' + ### Header + + Text text. + + [include:document-list]: ./ ({"level": 0}) + MARKDOWN, + ], + 'Level ``' => [ + <<<'MARKDOWN' + #### `<` Document B `>` + + Summary text. + + [Read more](). + + #### Document A + + Summary text with special characters `<`, `>`, `&`. + + [Read more](). + + MARKDOWN, + 'Document.md', + <<<'MARKDOWN' + # Header - self::assertEquals( - self::getTestData()->content('~NestedDirectories.md'), - << + Text text. - {$actual} - MARKDOWN, - ); + [include:document-list]: ./ ({"level": 4}) + MARKDOWN, + ], + ]; } + // } diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~AnotherDirectory.md b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~AnotherDirectory.md deleted file mode 100644 index 0559d6ac5..000000000 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~AnotherDirectory.md +++ /dev/null @@ -1,19 +0,0 @@ - - -## `<` Document B `>` - -Summary text. - -[Read more](). - -## Document - -Document summary. - -[Read more](). - -## Document A - -Summary text with special characters `<`, `>`, `&`. - -[Read more](). diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~NestedDirectories.md b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~NestedDirectories.md deleted file mode 100644 index 2260c9dd8..000000000 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~NestedDirectories.md +++ /dev/null @@ -1,19 +0,0 @@ - - -## Nested B - -Summary [text](../Document.md). - -[Read more](). - -## Nested A - -Summary [text](../Document.md). - -[Read more](). - -## Document C - -Summary [text](../Document.md) summary [link](../Document.md "title") and summary and self and self. - -[Read more](). diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~SameDirectory.md b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~SameDirectory.md deleted file mode 100644 index 5558e8f7f..000000000 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest~SameDirectory.md +++ /dev/null @@ -1,13 +0,0 @@ - - -## `<` Document B `>` - -Summary text. - -[Read more](). - -## Document A - -Summary text with special characters `<`, `>`, `&`. - -[Read more](). diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php index 441e30dc8..2f930de32 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Parameters.php @@ -33,6 +33,14 @@ public function __construct( * Sort order. */ public readonly SortOrder $order = SortOrder::Asc, + /** + * Headings level. Possible values are + * + * * `null`: ` + 1` + * * `int`: explicit level (`1-6`) + * * `0`: `` + */ + public readonly ?int $level = null, ) { // empty } diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php index 863ca5ea6..bc80f7958 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php @@ -8,6 +8,10 @@ public function __construct( * @var non-empty-list */ public array $documents, + /** + * @var int<1, 6> + */ + public int $level, ) { // empty } From c7a8a8480e5e48ab98437df9609173b7819d8fbd Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Thu, 28 Nov 2024 10:21:33 +0400 Subject: [PATCH 4/4] feat(documentator): `include:document-list` will render headers as links. --- packages/documentator/README.md | 6 ++-- .../views/document-list/default.blade.php | 2 +- .../IncludeDocumentList/InstructionTest.php | 28 +++++++++---------- packages/graphql-printer/README.md | 4 +-- packages/graphql/README.md | 20 ++++++------- packages/testing/README.md | 16 +++++------ 6 files changed, 38 insertions(+), 38 deletions(-) diff --git a/packages/documentator/README.md b/packages/documentator/README.md index b69973b00..f61d37aa7 100644 --- a/packages/documentator/README.md +++ b/packages/documentator/README.md @@ -38,19 +38,19 @@ composer require lastdragon-ru/lara-asp-documentator [//]: # (start: preprocess/820df828d96420b5) [//]: # (warning: Generated automatically. Do not edit.) -## `lara-asp-documentator:commands` +## [`lara-asp-documentator:commands`]() Saves help for each command in the `namespace` into a separate file in the `target` directory. [Read more](). -## `lara-asp-documentator:preprocess` +## [`lara-asp-documentator:preprocess`]() Perform one or more task on the file. [Read more](). -## `lara-asp-documentator:requirements` +## [`lara-asp-documentator:requirements`]() Generates a table with the required versions of PHP/Laravel/etc in Markdown format. diff --git a/packages/documentator/defaults/views/document-list/default.blade.php b/packages/documentator/defaults/views/document-list/default.blade.php index aff85a106..7085508ba 100644 --- a/packages/documentator/defaults/views/document-list/default.blade.php +++ b/packages/documentator/defaults/views/document-list/default.blade.php @@ -5,7 +5,7 @@ ?> @foreach ($data->documents as $document) -{{ str_repeat('#', $data->level) }} {!! $document->title !!} +{{ str_repeat('#', $data->level) }} [{!! $document->title !!}](<{{ $document->path }}>) @if($document->summary) {!! $document->summary !!} diff --git a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php index d95393864..d73766cbe 100644 --- a/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php +++ b/packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/InstructionTest.php @@ -66,13 +66,13 @@ public static function dataProviderInvoke(): array { return [ 'Same Directory / Default parameters' => [ <<<'MARKDOWN' - # `<` Document B `>` + # [`<` Document B `>`]() Summary text. [Read more](). - # Document A + # [Document A]() Summary text with special characters `<`, `>`, `&`. @@ -86,19 +86,19 @@ public static function dataProviderInvoke(): array { ], 'Another Directory / Default parameters' => [ <<<'MARKDOWN' - # `<` Document B `>` + # [`<` Document B `>`]() Summary text. [Read more](). - # Document + # [Document]() Document summary. [Read more](). - # Document A + # [Document A]() Summary text with special characters `<`, `>`, `&`. @@ -112,19 +112,19 @@ public static function dataProviderInvoke(): array { ], 'Nested Directories' => [ <<<'MARKDOWN' - # Nested B + # [Nested B]() Summary [text](../Document.md). [Read more](). - # Nested A + # [Nested A]() Summary [text](../Document.md). [Read more](). - # Document C + # [Document C]() Summary [text](../Document.md) summary [link](../Document.md "title") and summary and self and self. @@ -138,13 +138,13 @@ public static function dataProviderInvoke(): array { ], 'Level `null`' => [ <<<'MARKDOWN' - ## `<` Document B `>` + ## [`<` Document B `>`]() Summary text. [Read more](). - ## Document A + ## [Document A]() Summary text with special characters `<`, `>`, `&`. @@ -162,13 +162,13 @@ public static function dataProviderInvoke(): array { ], 'Level `0`' => [ <<<'MARKDOWN' - ### `<` Document B `>` + ### [`<` Document B `>`]() Summary text. [Read more](). - ### Document A + ### [Document A]() Summary text with special characters `<`, `>`, `&`. @@ -186,13 +186,13 @@ public static function dataProviderInvoke(): array { ], 'Level ``' => [ <<<'MARKDOWN' - #### `<` Document B `>` + #### [`<` Document B `>`]() Summary text. [Read more](). - #### Document A + #### [Document A]() Summary text with special characters `<`, `>`, `&`. diff --git a/packages/graphql-printer/README.md b/packages/graphql-printer/README.md index 6090c66ec..84f4ab7e6 100644 --- a/packages/graphql-printer/README.md +++ b/packages/graphql-printer/README.md @@ -227,13 +227,13 @@ It is highly recommended to use [`lara-asp-graphql`](../graphql/README.md#printe [//]: # (start: preprocess/c79a463462fd8331) [//]: # (warning: Generated automatically. Do not edit.) -## `assertGraphQLExportableEquals` +## [`assertGraphQLExportableEquals`]() Exports and compares two GraphQL schemas/types/nodes/etc. [Read more](). -## `assertGraphQLPrintableEquals` +## [`assertGraphQLPrintableEquals`]() Prints and compares two GraphQL schemas/types/nodes/etc. diff --git a/packages/graphql/README.md b/packages/graphql/README.md index 5e58f7543..4dd3713d9 100644 --- a/packages/graphql/README.md +++ b/packages/graphql/README.md @@ -57,25 +57,25 @@ php artisan vendor:publish --provider=LastDragon_ru\\LaraASP\\GraphQL\\PackagePr [//]: # (start: preprocess/bda62d219016136a) [//]: # (warning: Generated automatically. Do not edit.) -## `@searchBy` +## [`@searchBy`]() Probably the most powerful directive to provide search (`where` conditions) for your GraphQL queries. [Read more](). -## `@sortBy` +## [`@sortBy`]() Probably the most powerful directive to provide sort (`order by` conditions) for your GraphQL queries. [Read more](). -## `@stream` ๐Ÿงช +## [`@stream` ๐Ÿงช]() Unlike the `@paginate` (and similar) directive, the `@stream` provides a uniform way to perform Offset/Limit and Cursor pagination of Eloquent/Query/Scout builders. Filtering and sorting enabled by default via [`@searchBy`](docs/Directives/@searchBy.md) and [`@sortBy`](docs/Directives/@sortBy.md) directives. [Read more](). -## `@type` +## [`@type`]() Converts scalar into GraphQL Type. Similar to Lighthouse's `@scalar` directive, but uses Laravel Container to resolve instance and also supports PHP enums. @@ -100,7 +100,7 @@ Converts scalar into GraphQL Type. Similar to Lighthouse's `@scalar` directive, [//]: # (start: preprocess/e0862296ba011303) [//]: # (warning: Generated automatically. Do not edit.) -## `JsonString` +## [`JsonString`]() Represents [JSON](https://json.org) string. @@ -560,31 +560,31 @@ type User { [//]: # (start: preprocess/c79a463462fd8331) [//]: # (warning: Generated automatically. Do not edit.) -## `assertGraphQLIntrospectionEquals` +## [`assertGraphQLIntrospectionEquals`]() Compares default public schema (as the client sees it through introspection). [Read more](). -## `assertGraphQLSchemaEquals` +## [`assertGraphQLSchemaEquals`]() Compares default internal schema (with all directives). [Read more](). -## `assertGraphQLSchemaNoBreakingChanges` +## [`assertGraphQLSchemaNoBreakingChanges`]() Checks that no breaking changes in the default internal schema (with all directives). [Read more](). -## `assertGraphQLSchemaNoDangerousChanges` +## [`assertGraphQLSchemaNoDangerousChanges`]() Checks that no dangerous changes in the default internal schema (with all directives). [Read more](). -## `assertGraphQLSchemaValid` +## [`assertGraphQLSchemaValid`]() Validates default internal schema (with all directives). Faster than `lighthouse:validate-schema` command because loads only used directives. diff --git a/packages/testing/README.md b/packages/testing/README.md index 3036cfb1d..a1ada7c83 100644 --- a/packages/testing/README.md +++ b/packages/testing/README.md @@ -260,49 +260,49 @@ Disable models events during make/create. [//]: # (start: preprocess/c79a463462fd8331) [//]: # (warning: Generated automatically. Do not edit.) -## `assertDatabaseQueryEquals` +## [`assertDatabaseQueryEquals`]() Asserts that SQL Query equals SQL Query. [Read more](). -## `assertJsonMatchesSchema` +## [`assertJsonMatchesSchema`]() Asserts that JSON matches [schema](https://json-schema.org/). Validation based on the [Opis JSON Schema](https://github.com/opis/json-schema) package. [Read more](). -## `assertPsrResponse` +## [`assertPsrResponse`]() Asserts that PSR Response satisfies given constraint (we have a lot of built-in [constraints](src/Constraints/Response) and [responses](src/Responses), but, of course, you can create a custom). [Read more](). -## `assertQueryLogEquals` +## [`assertQueryLogEquals`]() Asserts that `QueryLog` equals `QueryLog`. [Read more](). -## `assertScheduled` +## [`assertScheduled`]() Asserts that Schedule contains task. [Read more](). -## `assertScoutQueryEquals` +## [`assertScoutQueryEquals`]() Asserts that Scout Query equals Scout Query. [Read more](). -## `assertThatResponse` ๐Ÿ’€ +## [`assertThatResponse` ๐Ÿ’€]() Asserts that PSR Response satisfies given constraint (we have a lot of built-in [constraints](src/Constraints/Response) and [responses](src/Responses), but, of course, you can create a custom). [Read more](). -## `assertXmlMatchesSchema` +## [`assertXmlMatchesSchema`]() Asserts that XML matches schema [XSD](https://en.wikipedia.org/wiki/XML_Schema_(W3C)) or [Relax NG](https://en.wikipedia.org/wiki/RELAX_NG). Validation based on the standard methods of [`DOMDocument`](https://www.php.net/manual/en/class.domdocument.php) class.