[2.x] Rewrite documentation search page internals to be based on dynamic pages instead of a build task

RELEASE_NOTES.md

@@ -10,16 +10,17 @@ This serves two purposes:
 2. At release time, you can move the Unreleased section changes into a new release version section.
 
 ### Added
-- for new features.
+- Add experimental `InMemoryPage::getOutputPath` overload support
 
 ### Changed
-- for changes in existing functionality.
+- Changed how the documentation search is generated, to be an `InMemoryPage` instead of a post-build task.
+- Updated the documentation article component to support existing `$document` instance.
 
 ### Deprecated
 - for soon-to-be removed features.
 
 ### Removed
-- for now removed features.
+- Breaking: Removed the build task `\Hyde\Framework\Actions\PostBuildTasks\GenerateSearch` (see upgrade guide below)
 
 ### Fixed
 - for any bug fixes.
@@ -30,3 +31,30 @@ This serves two purposes:
 ### Upgrade Guide
 
 If there are any breaking changes, include an upgrade guide here.
+
+#### Documentation search page changes
+
+The documentation search page and search index have been changed to be generated as `InMemoryPages` instead of a post-build task.
+
+The main impact noticeable to most users by this is the implicit changes, like the pages showing up in the dashboard and route list command.
+
+In case you have customized the `GenerateSearch` post-build task you may, depending on what you were trying to do, 
+want to adapt your code to interact with the new `InMemoryPage`, which is generated in the `HydeCoreExtension` class.
+
+For more information, see https://github.com/hydephp/develop/pull/1498.
+
+### Breaking changes
+
+#### Low impact
+
+- The `GenerateSearch` post-build task has been removed. If you have previously extended or customized this class, 
+  you will need to adapt your code, as the search index files are now handled implicitly during the standard build process,
+  as the search pages are now added to the kernel page and route collection. (https://github.com/hydephp/develop/pull/1498)
+
+- If your site has a custom documentation search page, for example `_docs/search.md` or `_pages/docs/search.blade.php`,
+  that page will no longer be built when using the specific `build:search` command. It will, of course, 
+  be built using the standard `build` command. https://github.com/hydephp/develop/commit/82dc71f4a0e7b6be7a9f8d822fbebe39d2289ced
+- 
+- In the highly unlikely event your site customizes any of the search pages by replacing them in the kernel route collection,
+  you would now need to do that in the kernel page collection due to the search pages being generated earlier in the lifecycle.
+  https://github.com/hydephp/develop/commit/82dc71f4a0e7b6be7a9f8d822fbebe39d2289ced

packages/framework/resources/views/components/docs/documentation-article.blade.php

@@ -1,5 +1,5 @@
 @php
-    $document = \Hyde\Framework\Features\Documentation\SemanticDocumentationArticle::make($page);
+    $document ??= \Hyde\Framework\Features\Documentation\SemanticDocumentationArticle::make($page);
 @endphp
 
 <article id="document" itemscope itemtype="https://schema.org/Article" @class([

packages/framework/src/Console/Commands/BuildSearchCommand.php

@@ -4,8 +4,11 @@
 
 namespace Hyde\Console\Commands;
 
-use Hyde\Framework\Actions\PostBuildTasks\GenerateSearch;
+use Hyde\Foundation\Facades\Pages;
+use Hyde\Framework\Actions\StaticPageBuilder;
 use LaravelZero\Framework\Commands\Command;
+use Hyde\Framework\Features\Documentation\DocumentationSearchPage;
+use Hyde\Framework\Features\Documentation\DocumentationSearchIndex;
 
 /**
  * Run the build process for the documentation search index.
@@ -20,6 +23,12 @@ class BuildSearchCommand extends Command
 
     public function handle(): int
     {
-        return (new GenerateSearch())->run($this->output);
+        StaticPageBuilder::handle(Pages::get('docs/search.json') ?? new DocumentationSearchIndex());
+
+        if (DocumentationSearchPage::enabled()) {
+            StaticPageBuilder::handle(Pages::get('docs/search') ?? new DocumentationSearchPage());
+        }
+
+        return Command::SUCCESS;
     }
 }

packages/framework/src/Foundation/HydeCoreExtension.php

@@ -9,8 +9,11 @@
 use Hyde\Pages\MarkdownPage;
 use Hyde\Pages\MarkdownPost;
 use Hyde\Pages\DocumentationPage;
+use Hyde\Foundation\Kernel\PageCollection;
 use Hyde\Foundation\Concerns\HydeExtension;
 use Hyde\Facades\Features;
+use Hyde\Framework\Features\Documentation\DocumentationSearchPage;
+use Hyde\Framework\Features\Documentation\DocumentationSearchIndex;
 
 use function array_filter;
 use function array_keys;
@@ -28,4 +31,15 @@ public static function getPageClasses(): array
             DocumentationPage::class => Features::hasDocumentationPages(),
         ], fn (bool $value): bool => $value));
     }
+
+    public function discoverPages(PageCollection $collection): void
+    {
+        if (Features::hasDocumentationSearch()) {
+            $collection->addPage(new DocumentationSearchIndex());
+
+            if (DocumentationSearchPage::enabled()) {
+                $collection->addPage(new DocumentationSearchPage());
+            }
+        }
+    }
 }

packages/framework/src/Framework/Actions/GeneratesDocumentationSearchIndex.php

@@ -26,7 +26,7 @@ class GeneratesDocumentationSearchIndex
     protected string $path;
 
     /**
-     * Generate the search index and save it to disk.
+     * @deprecated Generate the search index and save it to disk.
      *
      * @return string The path to the generated file.
      */
@@ -39,6 +39,17 @@ public static function handle(): string
         return $service->path;
     }
 
+    /**
+     * Generate the search index return it as a string.
+     */
+    public static function generate(): string
+    {
+        $service = new static();
+        $service->run();
+
+        return $service->index->toJson();
+    }
+
     protected function __construct()
     {
         $this->index = new Collection();
@@ -48,7 +59,7 @@ protected function __construct()
     protected function run(): void
     {
         DocumentationPage::all()->each(function (DocumentationPage $page): void {
-            if (! in_array($page->identifier, Config::getArray('docs.exclude_from_search', []))) {
+            if (! in_array($page->identifier, $this->getPagesToExcludeFromSearch())) {
                 $this->index->push($this->generatePageEntry($page));
             }
         });
@@ -92,4 +103,9 @@ protected function getPath(): string
     {
         return Hyde::sitePath(DocumentationPage::outputDirectory().'/search.json');
     }
+
+    protected function getPagesToExcludeFromSearch(): array
+    {
+        return array_merge(Config::getArray('docs.exclude_from_search', []), Config::getBool('docs.create_search_page', true) ? ['search'] : []);
+    }
 }

packages/framework/src/Framework/Features/Documentation/DocumentationSearchIndex.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Framework\Features\Documentation;
+
+use Hyde\Pages\InMemoryPage;
+use Hyde\Pages\DocumentationPage;
+use Hyde\Framework\Actions\GeneratesDocumentationSearchIndex;
+
+/**
+ * @internal This page is used to render the search index for the documentation.
+ */
+class DocumentationSearchIndex extends InMemoryPage
+{
+    /**
+     * Create a new DocumentationSearchPage instance.
+     */
+    public function __construct()
+    {
+        parent::__construct(ltrim(DocumentationPage::outputDirectory().'/search.json', '/'), [
+            'navigation' => ['hidden' => true],
+        ]);
+    }
+
+    public function compile(): string
+    {
+        return GeneratesDocumentationSearchIndex::generate();
+    }
+
+    public function getOutputPath(): string
+    {
+        return ltrim(DocumentationPage::outputDirectory().'/search.json', '/');
+    }
+}

packages/framework/src/Framework/Features/Documentation/DocumentationSearchPage.php

@@ -5,10 +5,11 @@
 namespace Hyde\Framework\Features\Documentation;
 
 use Hyde\Hyde;
+use Hyde\Pages\InMemoryPage;
 use Hyde\Pages\DocumentationPage;
+use Hyde\Pages\Concerns\HydePage;
 use Hyde\Framework\Actions\StaticPageBuilder;
 use Hyde\Facades\Config;
-use Illuminate\Support\Facades\View;
 
 /**
  * @internal This page is used to render the search page for the documentation.
@@ -17,7 +18,7 @@
  * If you want to override this page, you can create a page with the route key "docs/search",
  * then this class will not be applied. For example, `_pages/docs/search.blade.php`.
  */
-class DocumentationSearchPage extends DocumentationPage
+class DocumentationSearchPage extends InMemoryPage
 {
     /**
      * Generate the search page and save it to disk.
@@ -34,23 +35,32 @@ public static function generate(): string
      */
     public function __construct()
     {
-        parent::__construct('search', [
+        parent::__construct(ltrim(DocumentationPage::outputDirectory().'/search', '/'), [
             'title' => 'Search',
-        ]);
+            'navigation' => ['hidden' => true],
+            'document' => $this->makeDocument(),
+        ], view: 'hyde::pages.documentation-search');
     }
 
-    public function compile(): string
+    public static function enabled(): bool
     {
-        return View::make('hyde::pages.documentation-search')->render();
+        return Config::getBool('docs.create_search_page', true) && ! static::anotherSearchPageExists();
     }
 
-    public static function enabled(): bool
+    protected static function anotherSearchPageExists(): bool
+    {
+        // Since routes aren't discovered yet, we need to check the pages directly
+        return Hyde::pages()->first(fn (HydePage $file): bool => $file->getRouteKey() === static::routeKey()) !== null;
+    }
+
+    protected static function routeKey(): string
     {
-        return Config::getBool('docs.create_search_page', true) && ! Hyde::routes()->has(self::routeKey());
+        return ltrim(DocumentationPage::outputDirectory().'/search');
     }
 
-    public static function routeKey(): string
+    /** @experimental Fixes type issue {@see https://github.com/hydephp/develop/commit/37f7046251b8c0514b8d8ef821de4ef3d35bbac8#commitcomment-135026537} */
+    protected function makeDocument(): SemanticDocumentationArticle
     {
-        return parent::outputDirectory().'/search';
+        return SemanticDocumentationArticle::make(new DocumentationPage());
     }
 }

packages/framework/src/Framework/Services/BuildTaskService.php

@@ -11,7 +11,6 @@
 use Hyde\Framework\Features\BuildTasks\PreBuildTask;
 use Hyde\Framework\Features\BuildTasks\PostBuildTask;
 use Hyde\Framework\Actions\PreBuildTasks\CleanSiteDirectory;
-use Hyde\Framework\Actions\PostBuildTasks\GenerateSearch;
 use Hyde\Framework\Actions\PostBuildTasks\GenerateRssFeed;
 use Hyde\Framework\Actions\PostBuildTasks\GenerateSitemap;
 use Hyde\Framework\Actions\PostBuildTasks\GenerateBuildManifest;
@@ -136,7 +135,6 @@ private function registerFrameworkTasks(): void
         $this->registerIf(GenerateBuildManifest::class, $this->canGenerateManifest());
         $this->registerIf(GenerateSitemap::class, $this->canGenerateSitemap());
         $this->registerIf(GenerateRssFeed::class, $this->canGenerateFeed());
-        $this->registerIf(GenerateSearch::class, $this->canGenerateSearch());
     }
 
     private function canCleanSiteDirectory(): bool
@@ -158,9 +156,4 @@ private function canGenerateFeed(): bool
     {
         return Features::rss();
     }
-
-    private function canGenerateSearch(): bool
-    {
-        return Features::hasDocumentationSearch();
-    }
 }

packages/framework/src/Pages/InMemoryPage.php

@@ -82,6 +82,16 @@ public function getBladeView(): string
         return $this->view;
     }
 
+    /** @experimental Get the path to the output file for the page. */
+    public function getOutputPath(): string
+    {
+        if ($this->hasMacro('getOutputPath')) {
+            return $this->__call('getOutputPath', []);
+        }
+
+        return parent::getOutputPath();
+    }
+
     /**
      * Get the contents that will be saved to disk for this page.
      *

packages/framework/tests/Feature/Commands/BuildSearchCommandTest.php

@@ -6,13 +6,14 @@
 
 use Hyde\Facades\Filesystem;
 use Hyde\Hyde;
+use Hyde\Pages\InMemoryPage;
 use Hyde\Pages\DocumentationPage;
 use Hyde\Testing\TestCase;
 
 /**
  * @covers \Hyde\Console\Commands\BuildSearchCommand
- * @covers \Hyde\Framework\Actions\PostBuildTasks\GenerateSearch
  * @covers \Hyde\Framework\Features\Documentation\DocumentationSearchPage
+ * @covers \Hyde\Framework\Features\Documentation\DocumentationSearchIndex
  */
 class BuildSearchCommandTest extends TestCase
 {
@@ -103,4 +104,27 @@ public function test_search_files_can_be_generated_for_custom_site_and_nested_do
 
         Filesystem::deleteDirectory('foo');
     }
+
+    public function test_command_uses_search_pages_from_kernel_when_present()
+    {
+        Hyde::pages()->addPage(tap(new InMemoryPage('docs/search.json'), function (InMemoryPage $page): void {
+            $page->macro('compile', fn () => '{"foo":"bar"}');
+            $page->macro('getOutputPath', fn () => 'docs/search.json');
+        }));
+
+        Hyde::pages()->addPage(tap(new InMemoryPage('docs/search'), function (InMemoryPage $page): void {
+            $page->macro('compile', fn () => 'Foo');
+        }));
+
+        $this->artisan('build:search')->assertExitCode(0);
+
+        $this->assertFileExists(Hyde::path('_site/docs/search.json'));
+//        $this->assertFileExists(Hyde::path('_site/docs/search.html'));
+
+        $this->assertSame('{"foo":"bar"}', Filesystem::getContents('_site/docs/search.json'));
+//        $this->assertSame('Foo', Filesystem::getContents('_site/docs/search.html'));
+
+        Filesystem::unlink('_site/docs/search.json');
+//        Filesystem::unlink('_site/docs/search.html');
+    }
 }