From bf03f52b4b075ae1294f943daf37fc620f28934b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 6 May 2022 21:48:14 +0200 Subject: [PATCH 1/8] Deprecate the action --- src/Actions/GeneratesDocumentationSidebar.php | 1 + tests/Feature/GeneratesDocumentationSidebarTest.php | 1 + 2 files changed, 2 insertions(+) diff --git a/src/Actions/GeneratesDocumentationSidebar.php b/src/Actions/GeneratesDocumentationSidebar.php index 5540f994..23241e2e 100644 --- a/src/Actions/GeneratesDocumentationSidebar.php +++ b/src/Actions/GeneratesDocumentationSidebar.php @@ -9,6 +9,7 @@ /** * Create the sidebar items for the documentation page. + * @deprecated use the DocumentationSidebarService instead */ class GeneratesDocumentationSidebar { diff --git a/tests/Feature/GeneratesDocumentationSidebarTest.php b/tests/Feature/GeneratesDocumentationSidebarTest.php index 995da603..fb19af5b 100644 --- a/tests/Feature/GeneratesDocumentationSidebarTest.php +++ b/tests/Feature/GeneratesDocumentationSidebarTest.php @@ -8,6 +8,7 @@ /** * @covers \Hyde\Framework\Actions\GeneratesDocumentationSidebar + * @deprecated use the DocumentationSidebarServiceTest instead */ class GeneratesDocumentationSidebarTest extends TestCase { From cb3c3371b71210957a35c63219003982411bff66 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 7 May 2022 11:40:55 +0200 Subject: [PATCH 2/8] Define the contracts --- .../DocumentationSidebarContract.php | 23 +++++++++++++++++++ .../DocumentationSidebarServiceContract.php | 23 +++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 src/Contracts/DocumentationSidebarContract.php create mode 100644 src/Contracts/DocumentationSidebarServiceContract.php diff --git a/src/Contracts/DocumentationSidebarContract.php b/src/Contracts/DocumentationSidebarContract.php new file mode 100644 index 00000000..61020e05 --- /dev/null +++ b/src/Contracts/DocumentationSidebarContract.php @@ -0,0 +1,23 @@ + Date: Sat, 7 May 2022 11:50:00 +0200 Subject: [PATCH 3/8] Create the sidebar models --- src/Models/DocumentationSidebar.php | 36 ++++++++++++++++++ src/Models/DocumentationSidebarItem.php | 49 +++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 src/Models/DocumentationSidebar.php create mode 100644 src/Models/DocumentationSidebarItem.php diff --git a/src/Models/DocumentationSidebar.php b/src/Models/DocumentationSidebar.php new file mode 100644 index 00000000..7b32f0dc --- /dev/null +++ b/src/Models/DocumentationSidebar.php @@ -0,0 +1,36 @@ +push($item); + + return $this; + } + + public function sortItems(): self + { + return $this->sortBy('priority') + ->values(); // Reset the keys to consecutively numbered indexes: + } + + public function getCollection(): self + { + return $this; + } +} \ No newline at end of file diff --git a/src/Models/DocumentationSidebarItem.php b/src/Models/DocumentationSidebarItem.php new file mode 100644 index 00000000..436f62cc --- /dev/null +++ b/src/Models/DocumentationSidebarItem.php @@ -0,0 +1,49 @@ +label = $label; + $this->destination = $destination; + $this->priority = $priority ?? $this->findPriorityInConfig($destination); + } + + protected function findPriorityInConfig(string $slug): int + { + $orderIndexArray = config('hyde.documentationPageOrder', []); + + if (! in_array($slug, $orderIndexArray)) { + return 500; + } + + return array_search($slug, $orderIndexArray); // + 250? + } + + public static function parseFromFile(string $documentationPageSlug): static + { + $matter = YamlFrontMatter::markdownCompatibleParse( + file_get_contents(Hyde::path('_docs/' . $documentationPageSlug . '.md')) + )->matter(); + + return new static( + $matter['label'] ?? Hyde::titleFromSlug($documentationPageSlug), + $documentationPageSlug, + $matter['priority'] ?? null + ); + } +} \ No newline at end of file From 14d62b9f6217cacdf41760ffce0fdc0aabd9a4ed Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 7 May 2022 11:50:23 +0200 Subject: [PATCH 4/8] Create the sidebar service class --- src/Services/DocumentationSidebarService.php | 81 ++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 src/Services/DocumentationSidebarService.php diff --git a/src/Services/DocumentationSidebarService.php b/src/Services/DocumentationSidebarService.php new file mode 100644 index 00000000..775d7195 --- /dev/null +++ b/src/Services/DocumentationSidebarService.php @@ -0,0 +1,81 @@ +createSidebar()->withoutIndex()->getSidebar() + )->sortItems()->getCollection(); + } + + /** + * Parse the _docs directory for sidebar items to create a new collection. + */ + public function createSidebar(): self + { + $this->sidebar = new DocumentationSidebar(); + + foreach ($this->getSidebarItems() as $slug) { + $this->sidebar->addItem( + $this->createSidebarItemFromSlug($slug) + ); + } + + return $this; + } + + /** + * Get the sidebar object created and managed by the service instance. + */ + public function getSidebar(): DocumentationSidebar + { + return $this->sidebar; + } + + /** + * Remove the index page from the sidebar collection. + */ + protected function withoutIndex(): self + { + $this->sidebar = $this->sidebar->reject(function (DocumentationSidebarItem $item) { + return $item->destination === 'index'; + }); + + return $this; + } + + /** + * Get an array of source files to add to the sidebar. + */ + protected function getSidebarItems(): array + { + return CollectionService::getDocumentationPageList(); + } + + /** + * Generate a SidebarItem object from a source file referenced by its slug. + */ + protected function createSidebarItemFromSlug(string $slug): DocumentationSidebarItem + { + return DocumentationSidebarItem::parseFromFile($slug); + } +} \ No newline at end of file From 0adf94889c36e0b77fb63018221b16c7f1fc8374 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 7 May 2022 11:50:58 +0200 Subject: [PATCH 5/8] Create feature test for the new sidebar service --- .../DocumentationSidebarServiceTest.php | 156 ++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 tests/Feature/Services/DocumentationSidebarServiceTest.php diff --git a/tests/Feature/Services/DocumentationSidebarServiceTest.php b/tests/Feature/Services/DocumentationSidebarServiceTest.php new file mode 100644 index 00000000..6ee9912b --- /dev/null +++ b/tests/Feature/Services/DocumentationSidebarServiceTest.php @@ -0,0 +1,156 @@ +resetDocsDirectory(); + } + + protected function tearDown(): void + { + $this->resetDocsDirectory(); + + parent::tearDown(); + } + + public function test_sidebar_can_be_created() + { + $service = new DocumentationSidebarService(); + $sidebar = $service->createSidebar()->getSidebar(); + + $this->assertInstanceOf(DocumentationSidebar::class, $sidebar); + } + + public function test_sidebar_items_can_be_added() + { + $sidebar = DocumentationSidebarService::get()->addItem( + new DocumentationSidebarItem('test', 'test') + ); + + $this->assertCount(1, $sidebar); + $this->assertInstanceOf(DocumentationSidebarItem::class, $sidebar[0]); + } + + public function test_sidebar_items_are_added_automatically() + { + $this->createTestFiles(); + + $sidebar = DocumentationSidebarService::get(); + + $this->assertCount(5, $sidebar); + } + + public function test_index_page_is_removed_from_sidebar() + { + $this->createTestFiles(); + touch(Hyde::path('_docs/index.md')); + + $sidebar = DocumentationSidebarService::get(); + $this->assertCount(5, $sidebar); + } + + public function test_sidebar_is_ordered_alphabetically_when_no_order_is_set_in_config() + { + Config::set('hyde.documentationPageOrder', []); + touch(Hyde::path('_docs/alpha.md')); + touch(Hyde::path('_docs/bravo.md')); + touch(Hyde::path('_docs/charlie.md')); + + $sidebar = DocumentationSidebarService::get(); + + $this->assertEquals('alpha', $sidebar[0]->destination); + $this->assertEquals('bravo', $sidebar[1]->destination); + $this->assertEquals('charlie', $sidebar[2]->destination); + } + + public function test_sidebar_is_ordered_by_priority_when_priority_is_set_in_config() + { + Config::set('hyde.documentationPageOrder', [ + 'charlie', + 'bravo', + 'alpha', + ]); + touch(Hyde::path('_docs/alpha.md')); + touch(Hyde::path('_docs/bravo.md')); + touch(Hyde::path('_docs/charlie.md')); + + $sidebar = DocumentationSidebarService::get(); + $this->assertEquals('charlie', $sidebar[0]->destination); + $this->assertEquals('bravo', $sidebar[1]->destination); + $this->assertEquals('alpha', $sidebar[2]->destination); + } + + public function test_sidebar_item_priority_can_be_set_in_front_matter() + { + file_put_contents( + Hyde::path('_docs/foo.md'), + (new ConvertsArrayToFrontMatter)->execute([ + 'priority' => 25, + ]) + ); + + $this->assertEquals(25, DocumentationSidebarItem::parseFromFile('foo')->priority); + $this->assertEquals(25, DocumentationSidebarService::get()->first()->priority); + } + + public function test_sidebar_item_priority_set_in_config_overrides_front_matter() + { + file_put_contents(Hyde::path('_docs/foo.md'), + (new ConvertsArrayToFrontMatter)->execute(['priority' => 25]) + ); + + Config::set('hyde.documentationPageOrder', ['foo']); + + $this->assertEquals(25, DocumentationSidebarService::get()->first()->priority); + } + + public function test_both_sidebar_priority_setting_methods_can_be_used() + { + Config::set('hyde.documentationPageOrder', [ + 'first', + 'third', + 'second', + ]); + touch(Hyde::path('_docs/first.md')); + touch(Hyde::path('_docs/second.md')); + file_put_contents(Hyde::path('_docs/third.md'), + (new ConvertsArrayToFrontMatter)->execute(['priority' => 3]) + ); + $sidebar = DocumentationSidebarService::get(); + $this->assertEquals('first', $sidebar[0]->destination); + $this->assertEquals('second', $sidebar[1]->destination); + $this->assertEquals('third', $sidebar[2]->destination); + } + + protected function resetDocsDirectory(): void + { + File::deleteDirectory(Hyde::path('_docs')); + mkdir(Hyde::path('_docs')); + } + + protected function createTestFiles(int $count = 5): void + { + for ($i = 0; $i < $count; $i++) { + touch(Hyde::path('_docs/test-' . $i . '.md')); + } + } +} From 30e74a9e89393504cd2155b14f2b04c9c89349bc Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 7 May 2022 11:52:14 +0200 Subject: [PATCH 6/8] Clarify namespace in PHPDoc to fix PHPStorm grammar check --- src/Models/DocumentationSidebar.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Models/DocumentationSidebar.php b/src/Models/DocumentationSidebar.php index 7b32f0dc..def34ae5 100644 --- a/src/Models/DocumentationSidebar.php +++ b/src/Models/DocumentationSidebar.php @@ -8,7 +8,7 @@ /** * The documentation sidebar, containing all the sidebar items. * - * Extends the Illuminate\Support\Collection class and has helper + * Extends the \Illuminate\Support\Collection class and has helper * methods to fluently add DocumentationSidebarItems to the * collection using method chaining. * From affb86a9a5ff753f6279450d008ba18e0e91cb2a Mon Sep 17 00:00:00 2001 From: StyleCI Bot Date: Sat, 7 May 2022 09:52:50 +0000 Subject: [PATCH 7/8] Apply fixes from StyleCI [ci skip] [skip ci] --- src/Actions/GeneratesDocumentationSidebar.php | 1 + src/Contracts/DocumentationSidebarContract.php | 2 +- src/Contracts/DocumentationSidebarServiceContract.php | 2 +- src/Models/DocumentationSidebar.php | 8 ++++---- src/Models/DocumentationSidebarItem.php | 6 +++--- src/Services/DocumentationSidebarService.php | 4 ++-- tests/Feature/GeneratesDocumentationSidebarTest.php | 1 + .../Feature/Services/DocumentationSidebarServiceTest.php | 2 +- 8 files changed, 14 insertions(+), 12 deletions(-) diff --git a/src/Actions/GeneratesDocumentationSidebar.php b/src/Actions/GeneratesDocumentationSidebar.php index 23241e2e..7c78b661 100644 --- a/src/Actions/GeneratesDocumentationSidebar.php +++ b/src/Actions/GeneratesDocumentationSidebar.php @@ -9,6 +9,7 @@ /** * Create the sidebar items for the documentation page. + * * @deprecated use the DocumentationSidebarService instead */ class GeneratesDocumentationSidebar diff --git a/src/Contracts/DocumentationSidebarContract.php b/src/Contracts/DocumentationSidebarContract.php index 61020e05..69d339e4 100644 --- a/src/Contracts/DocumentationSidebarContract.php +++ b/src/Contracts/DocumentationSidebarContract.php @@ -20,4 +20,4 @@ public function sortItems(): self; * Get the collection instance. */ public function getCollection(): self; -} \ No newline at end of file +} diff --git a/src/Contracts/DocumentationSidebarServiceContract.php b/src/Contracts/DocumentationSidebarServiceContract.php index e7296f1b..29dbde3c 100644 --- a/src/Contracts/DocumentationSidebarServiceContract.php +++ b/src/Contracts/DocumentationSidebarServiceContract.php @@ -20,4 +20,4 @@ public function createSidebar(): self; * Get the collection of sidebar items in the class. */ public function getSidebar(): DocumentationSidebar; -} \ No newline at end of file +} diff --git a/src/Models/DocumentationSidebar.php b/src/Models/DocumentationSidebar.php index def34ae5..77a6c497 100644 --- a/src/Models/DocumentationSidebar.php +++ b/src/Models/DocumentationSidebar.php @@ -7,11 +7,11 @@ /** * The documentation sidebar, containing all the sidebar items. - * + * * Extends the \Illuminate\Support\Collection class and has helper - * methods to fluently add DocumentationSidebarItems to the + * methods to fluently add DocumentationSidebarItems to the * collection using method chaining. - * + * * @see \Tests\Feature\Services\DocumentationSidebarServiceTest */ class DocumentationSidebar extends Collection implements DocumentationSidebarContract @@ -33,4 +33,4 @@ public function getCollection(): self { return $this; } -} \ No newline at end of file +} diff --git a/src/Models/DocumentationSidebarItem.php b/src/Models/DocumentationSidebarItem.php index 436f62cc..a8bb1f13 100644 --- a/src/Models/DocumentationSidebarItem.php +++ b/src/Models/DocumentationSidebarItem.php @@ -7,7 +7,7 @@ /** * Object containing information for a sidebar item. - * + * * @see \Tests\Feature\Services\DocumentationSidebarServiceTest */ class DocumentationSidebarItem @@ -37,7 +37,7 @@ protected function findPriorityInConfig(string $slug): int public static function parseFromFile(string $documentationPageSlug): static { $matter = YamlFrontMatter::markdownCompatibleParse( - file_get_contents(Hyde::path('_docs/' . $documentationPageSlug . '.md')) + file_get_contents(Hyde::path('_docs/'.$documentationPageSlug.'.md')) )->matter(); return new static( @@ -46,4 +46,4 @@ public static function parseFromFile(string $documentationPageSlug): static $matter['priority'] ?? null ); } -} \ No newline at end of file +} diff --git a/src/Services/DocumentationSidebarService.php b/src/Services/DocumentationSidebarService.php index 775d7195..5722e2e0 100644 --- a/src/Services/DocumentationSidebarService.php +++ b/src/Services/DocumentationSidebarService.php @@ -8,7 +8,7 @@ /** * Service class to create and manage the sidebar collection object. - * + * * @see \Tests\Feature\Services\DocumentationSidebarServiceTest */ class DocumentationSidebarService implements DocumentationSidebarServiceContract @@ -78,4 +78,4 @@ protected function createSidebarItemFromSlug(string $slug): DocumentationSidebar { return DocumentationSidebarItem::parseFromFile($slug); } -} \ No newline at end of file +} diff --git a/tests/Feature/GeneratesDocumentationSidebarTest.php b/tests/Feature/GeneratesDocumentationSidebarTest.php index fb19af5b..e3d3c444 100644 --- a/tests/Feature/GeneratesDocumentationSidebarTest.php +++ b/tests/Feature/GeneratesDocumentationSidebarTest.php @@ -8,6 +8,7 @@ /** * @covers \Hyde\Framework\Actions\GeneratesDocumentationSidebar + * * @deprecated use the DocumentationSidebarServiceTest instead */ class GeneratesDocumentationSidebarTest extends TestCase diff --git a/tests/Feature/Services/DocumentationSidebarServiceTest.php b/tests/Feature/Services/DocumentationSidebarServiceTest.php index 6ee9912b..74593f51 100644 --- a/tests/Feature/Services/DocumentationSidebarServiceTest.php +++ b/tests/Feature/Services/DocumentationSidebarServiceTest.php @@ -150,7 +150,7 @@ protected function resetDocsDirectory(): void protected function createTestFiles(int $count = 5): void { for ($i = 0; $i < $count; $i++) { - touch(Hyde::path('_docs/test-' . $i . '.md')); + touch(Hyde::path('_docs/test-'.$i.'.md')); } } } From 63b7c96b50149f015bba83299e32ca7ed918f1e5 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Sat, 7 May 2022 12:56:21 +0200 Subject: [PATCH 8/8] Update layout to use new sidebar --- resources/views/layouts/docs.blade.php | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/resources/views/layouts/docs.blade.php b/resources/views/layouts/docs.blade.php index 17bcd1ce..5ce3a74e 100644 --- a/resources/views/layouts/docs.blade.php +++ b/resources/views/layouts/docs.blade.php @@ -40,24 +40,22 @@ @endif @include('hyde::components.navigation.theme-toggle-button') -