feat(documentator)!: template parameter support for `IncludePackage…

…List` (`include:include:package-list`).
LastDragon-ru · Jan 18, 2024 · d2dbf7f · d2dbf7f
1 parent af8f2e4
commit d2dbf7f
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 9 deletions.
diff --git a/packages/documentator/docs/Commands/preprocess.md b/packages/documentator/docs/Commands/preprocess.md
@@ -75,9 +75,11 @@ Executes the `<target>` and returns result.
 
 Includes the `<target>` file.
 
-### `[include:package-list]: <target>`
+### `[include:package-list]: <target> <parameters>`
 
 * `<target>` - Directory path.
+* `<parameters>` - additional parameters
+  * `template` - Blade template
 
 Generates package list from `<target>` directory. The readme file will be
 used to determine package name and summary.

diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList.php
@@ -4,13 +4,14 @@
 
 use Exception;
 use LastDragon_ru\LaraASP\Documentator\PackageViewer;
-use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction;
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DocumentTitleIsMissing;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PackageComposerJsonIsMissing;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PackageReadmeIsMissing;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirectory;
 use LastDragon_ru\LaraASP\Documentator\Utils\Markdown;
 use LastDragon_ru\LaraASP\Documentator\Utils\Path;
+use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable;
 use Override;
 use Symfony\Component\Finder\Finder;
 
@@ -27,7 +28,10 @@
 
 use const JSON_THROW_ON_ERROR;
 
-class IncludePackageList implements ProcessableInstruction {
+/**
+ * @implements ParameterizableInstruction<IncludePackageListParameters>
+ */
+class IncludePackageList implements ParameterizableInstruction {
     public function __construct(
         protected readonly PackageViewer $viewer,
     ) {
@@ -53,7 +57,22 @@ public static function getTargetDescription(): ?string {
     }
 
     #[Override]
-    public function process(string $path, string $target): string {
+    public static function getParameters(): string {
+        return IncludePackageListParameters::class;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    #[Override]
+    public static function getParametersDescription(): array {
+        return [
+            'template' => 'Blade template',
+        ];
+    }
+
+    #[Override]
+    public function process(string $path, string $target, Serializable $parameters): string {
         // Directory?
         $root = Path::getPath(dirname($path), $target);
 
@@ -116,7 +135,8 @@ public function process(string $path, string $target): string {
         });
 
         // Render
-        $list = $this->viewer->render('package-list.markdown', [
+        $template = 'package-list.'.($parameters->template ?: 'markdown');
+        $list     = $this->viewer->render($template, [
             'packages' => $packages,
         ]);
 

diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageListParameters.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageListParameters.php
@@ -0,0 +1,13 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions;
+
+use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable;
+
+class IncludePackageListParameters implements Serializable {
+    public function __construct(
+        public readonly ?string $template = null,
+    ) {
+        // empty
+    }
+}
diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageListTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageListTest.php
@@ -19,8 +19,9 @@ final class IncludePackageListTest extends TestCase {
     public function testProcess(): void {
         $path     = self::getTestData()->file('Document.md')->getPathname();
         $target   = basename(self::getTestData()->path('/packages'));
+        $params   = new IncludePackageListParameters();
         $instance = Container::getInstance()->make(IncludePackageList::class);
-        $actual   = $instance->process($path, $target);
+        $actual   = $instance->process($path, $target, $params);
 
         self::assertEquals(
             self::getTestData()->content('.md'),
@@ -35,6 +36,7 @@ public function testProcess(): void {
     public function testProcessNotAPackage(): void {
         $path     = self::getTestData()->file('Document.md')->getPathname();
         $target   = basename(self::getTestData()->path('/invalid'));
+        $params   = new IncludePackageListParameters();
         $instance = Container::getInstance()->make(IncludePackageList::class);
 
         self::expectExceptionObject(
@@ -45,12 +47,13 @@ public function testProcessNotAPackage(): void {
             ),
         );
 
-        $instance->process($path, $target);
+        $instance->process($path, $target, $params);
     }
 
     public function testProcessNoReadme(): void {
         $path     = self::getTestData()->file('Document.md')->getPathname();
         $target   = basename(self::getTestData()->path('/no readme'));
+        $params   = new IncludePackageListParameters();
         $instance = Container::getInstance()->make(IncludePackageList::class);
 
         self::expectExceptionObject(
@@ -61,12 +64,13 @@ public function testProcessNoReadme(): void {
             ),
         );
 
-        $instance->process($path, $target);
+        $instance->process($path, $target, $params);
     }
 
     public function testProcessNoTitle(): void {
         $path     = self::getTestData()->file('Document.md')->getPathname();
         $target   = basename(self::getTestData()->path('/no title'));
+        $params   = new IncludePackageListParameters();
         $instance = Container::getInstance()->make(IncludePackageList::class);
 
         self::expectExceptionObject(
@@ -77,6 +81,6 @@ public function testProcessNoTitle(): void {
             ),
         );
 
-        $instance->process($path, $target);
+        $instance->process($path, $target, $params);
     }
 }