Extract documentation configuration options to docs.php

.github/dev-docs/RELEASE-NOTES-DRAFT.md

@@ -0,0 +1,26 @@
+# Draft for the release notes of upcoming HydePHP versions
+
+## Changes to the configuration files
+
+The entire configuration system has been refactored.
+
+### Snake_case is used for all configuration keys
+
+All configuration keys are now in the snake_case_format. Published configuration files will need to be updated accordingly. This is pretty fast in a modern code editor like VS Code.
+
+### Documentation options have been moved to a new file
+
+The documentation page specific options have been moved to the `config/docs.php` file.
+You may need to republish Blade views if you have done so before. 
+
+This is also easy to do in a modern code editor. See this example of the search and replace I used
+to update the codebase:
+
+`hyde.docs_sidebar_header_title` => `docs.header_title`
+
+
+### Deprecations and removals
+
+The deprecated option named `hyde.docs_directory` has been removed.
+
+Use `docs.output_directory` instead.

.github/dev-docs/documentation-pages.md

@@ -111,7 +111,7 @@ The default priority is 999. You can override the priority using the following f
 priority: 5
 ```
 
-You can also change the order in the Hyde configuration file.
+You can also change the order in the Docs configuration file.
 See [the chapter in the customization page](customization.html#navigation-menu--sidebar) for more details. <br>
  _I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._
 
@@ -162,20 +162,20 @@ including the documentation pages. Here is a high level overview for quick refer
 ### Output directory
 
 If you want to store the compiled documentation pages in a different directory than the default 'docs' directory,
-for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file.
+for example to specify a version like the Hyde docs does, you can specify the output directory in the Docs configuration file.
 
 ```php
-'docs_directory' => 'docs' // default
-'docs_directory' => 'docs/master' // What the Hyde docs use
+'output_directory' => 'docs' // default
+'output_directory' => 'docs/master' // What the Hyde docs use
 ```
 
 ### Sidebar header name
 
 By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs".
-You can change this in the Hyde configuration file.
+You can change this in the Docs configuration file.
 
 ```php
-'docs_sidebar_header_title' => 'API Documentation',
+'title' => 'API Documentation',
 ```
 
 ### Sidebar page order
@@ -184,7 +184,7 @@ To quickly arrange the order of items in the sidebar, you can reorder the page s
 Link items without an entry here will have fall back to the default priority of 999, putting them last.
 
 ```php
-'documentation_page_order' => [
+'sidebar_order' => [
     'readme',
     'installation',
     'getting-started',
@@ -196,11 +196,12 @@ See [the chapter in the customization page](customization.html#navigation-menu--
 
 ### Table of contents settings
 
-In the Hyde config you can configure the behavior, content, and the look and feel of the sidebar table of contents.
+In the `config/docs.php` file you can configure the behavior, content,
+and the look and feel of the sidebar table of contents.
 You can also disable the feature completely.
 
 ```php
-'documentation_page_table_of_contents' => [
+'table_of_contents' => [
 	'enabled' => true,
 	'min_heading_level' => 2,
 	'max_heading_level' => 4,

config/docs.php

@@ -0,0 +1,84 @@
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| Documentation Module Settings
+|--------------------------------------------------------------------------
+|
+| Since the Hyde documentation module has many configuration options,
+| they have now been broken out into their own configuration file.
+|
+*/
+
+return [
+	/*
+    |--------------------------------------------------------------------------
+    | Sidebar Header Name
+    |--------------------------------------------------------------------------
+    |
+    | By default, the sidebar title shown in the documentation page layouts uses
+    | the app name suffixed with "docs". You can change it with this setting.
+    |
+    */
+
+    'header_title' => config('hyde.name', 'HydePHP').' Docs',
+
+
+    /*
+    |--------------------------------------------------------------------------
+    | Documentation Site Output Directory
+    |--------------------------------------------------------------------------
+    |
+    | If you want to store the compiled documentation pages in a different
+    | directory than the default 'docs' directory, for example to set the
+    | specified version, you can specify the directory here.
+    |
+    | Note that you need to take care as to not set it to something that
+    | may conflict with other parts, such as media or posts directories.
+    |
+    | The default value is 'docs'. For easy versioning you can do what
+	| HydePHP.com does, setting it to 'docs/master'.
+    |
+    */
+
+    'output_directory' => 'docs',
+
+
+    /*
+    |--------------------------------------------------------------------------
+    | Sidebar Page Order
+    |--------------------------------------------------------------------------
+    |
+    | In the generated Documentation pages the navigation links in the sidebar
+    | are sorted alphabetically by default. As this rarely makes sense, you
+    | can reorder the page slugs in the list and the links will be sorted
+    | in that order. Link items without an entry here will have fall
+    | back to the default priority of 999, putting them last.
+    |
+    | You can also set explicit priorities in front matter.
+    |
+    */
+
+    'sidebar_order' => [
+        'readme',
+        'installation',
+        'getting-started',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Table of Contents Settings
+    |--------------------------------------------------------------------------
+    |
+    | The Hyde Documentation Module comes with a fancy Sidebar that, by default,
+    | has a Table of Contents included. Here, you can configure its behavior,
+    | content, look and feel. You can also disable the feature completely.
+    |
+    */
+
+    'table_of_contents' => [
+        'enabled' => true,
+        'min_heading_level' => 2,
+        'max_heading_level' => 4,
+    ],
+];

config/hyde.php

@@ -182,38 +182,7 @@
         '404',
     ],
 
-    /*
-    |--------------------------------------------------------------------------
-    | Documentation Sidebar Header Name
-    |--------------------------------------------------------------------------
-    |
-    | By default, the sidebar title shown in the documentation page layouts uses
-    | the app name suffixed with "docs". You can change it with this setting.
-    |
-    */
-
-    'docs_sidebar_header_title' => $siteName.' Docs',
-
-    /*
-    |--------------------------------------------------------------------------
-    | Documentation Site Output Directory
-    |--------------------------------------------------------------------------
-    |
-    | If you want to store the compiled documentation pages in a different
-    | directory than the default 'docs' directory, for example to set the
-    | specified version, you can specify the directory here.
-    |
-    | Note that you need to take care as to not set it to something that
-    | may conflict with other parts, such as media or posts directories.
-    |
-    | The default value is 'docs'.
-    |
-    */
-
-    /**
-     * @deprecated version 0.25.0, will be renamed to documentationOutputPath
-     */
-    'docs_directory' => 'docs',
+
 
     /*
     |--------------------------------------------------------------------------
@@ -230,41 +199,6 @@
 
     'site_output_path' => Hyde\Framework\Hyde::path('_site'),
 
-    /*
-    |--------------------------------------------------------------------------
-    | Documentation Sidebar Page Order
-    |--------------------------------------------------------------------------
-    |
-    | In the generated Documentation pages the navigation links in the sidebar
-    | are sorted alphabetically by default. As this rarely makes sense, you
-    | can reorder the page slugs in the list and the links will be sorted
-    | in that order. Link items without an entry here will have fall
-    | back to the default priority of 999, putting them last.
-    |
-    */
-
-    'documentation_page_order' => [
-        'readme',
-        'installation',
-        'getting-started',
-    ],
-
-    /*
-    |--------------------------------------------------------------------------
-    | Documentation Table of Contents Settings
-    |--------------------------------------------------------------------------
-    |
-    | The Hyde Documentation Module comes with a fancy Sidebar that, by default,
-    | has a Table of Contents included. Here, you can configure its behavior,
-    | content, look and feel. You can also disable the feature completely.
-    |
-    */
-
-    'documentation_page_table_of_contents' => [
-        'enabled' => true,
-        'min_heading_level' => 2,
-        'max_heading_level' => 4,
-    ],
 
     /*
     |--------------------------------------------------------------------------

resources/views/layouts/docs.blade.php

@@ -15,10 +15,10 @@
 		<strong class="mr-auto">
 			@if(Hyde::docsIndexPath() !== false)
 			<a href="{{ Hyde::relativeLink(Hyde::docsIndexPath(), $currentPage) }}">
-				{{ config('hyde.docs_sidebar_header_title', 'Documentation') }}
+				{{ config('docs.title', 'Documentation') }}
 			</a>
 			@else
-			{{ config('hyde.docs_sidebar_header_title', 'Documentation') }}
+			{{ config('docs.title', 'Documentation') }}
 			@endif
 		</strong>
         @include('hyde::components.navigation.theme-toggle-button')
@@ -35,10 +35,10 @@
 				<strong>
 					@if(Hyde::docsIndexPath() !== false)
 					<a href="{{ Hyde::relativeLink(Hyde::docsIndexPath(), $currentPage) }}">
-						{{ config('hyde.docs_sidebar_header_title', 'Documentation') }}
+						{{ config('docs.title', 'Documentation') }}
 					</a>
 					@else
-					{{ config('hyde.docs_sidebar_header_title', 'Documentation') }}
+					{{ config('docs.title', 'Documentation') }}
 					@endif
 				</strong>
 				@include('hyde::components.navigation.theme-toggle-button')

src/Actions/GeneratesTableOfContents.php

@@ -30,8 +30,8 @@ public function execute(): string
                 'html_class' => 'table-of-contents',
                 'position' => 'top',
                 'style' => 'bullet',
-                'min_heading_level' => config('hyde.documentation_page_table_of_contents.min_heading_level', 2),
-                'max_heading_level' => config('hyde.documentation_page_table_of_contents.max_heading_level', 4),
+                'min_heading_level' => config('docs.table_of_contents.min_heading_level', 2),
+                'max_heading_level' => config('docs.table_of_contents.max_heading_level', 4),
                 'normalize' => 'relative',
             ],
             'heading_permalink' => [

src/Concerns/HasTableOfContents.php

@@ -15,7 +15,7 @@ trait HasTableOfContents
 
     public function constructTableOfContents(): void
     {
-        if (config('hyde.documentation_page_table_of_contents.enabled', true)) {
+        if (config('docs.table_of_contents.enabled', true)) {
             $this->tableOfContents = (new GeneratesTableOfContents($this->body))->execute();
         }
     }

src/Concerns/Internal/FileHelpers.php

@@ -17,15 +17,15 @@ trait FileHelpers
      *
      * @deprecated will be renamed to be more distinct from other path helpers.
      *              Naming suggestion is `getDocumentationOutputPath()`.
-     *              The configuration is deprecated as well and will be renamed.
+     *              The configuration option has been renamed.
      *
      * @todo Test and if needed add support for storing documentation files in the site root
      *
      * @return string
      */
     public static function docsDirectory(): string
     {
-        return trim(config('hyde.docs_directory', 'docs'), '/\\');
+        return trim(config('docs.output_directory', 'docs'), '/\\');
     }
 
     /**

src/Concerns/Markdown/HasMarkdownFeatures.php

@@ -11,6 +11,6 @@ trait HasMarkdownFeatures
 {
     public static function hasTableOfContents(): bool
     {
-        return config('hyde.documentation_page_table_of_contents.enabled', true);
+        return config('docs.table_of_contents.enabled', true);
     }
 }

src/Models/DocumentationSidebarItem.php

@@ -30,7 +30,7 @@ public function __construct(string $label, string $destination, ?int $priority =
 
     protected function findPriorityInConfig(string $slug): int
     {
-        $orderIndexArray = config('hyde.documentationPageOrder', []);
+        $orderIndexArray = config('docs.sidebar_order', []);
 
         if (! in_array($slug, $orderIndexArray)) {
             return 500;

tests/Feature/Services/DocumentationSidebarServiceTest.php

@@ -79,7 +79,7 @@ public function test_files_with_front_matter_hidden_set_to_true_are_removed_from
 
     public function test_sidebar_is_ordered_alphabetically_when_no_order_is_set_in_config()
     {
-        Config::set('hyde.documentationPageOrder', []);
+        Config::set('docs.sidebar_order', []);
         touch(Hyde::path('_docs/alpha.md'));
         touch(Hyde::path('_docs/bravo.md'));
         touch(Hyde::path('_docs/charlie.md'));
@@ -93,7 +93,7 @@ public function test_sidebar_is_ordered_alphabetically_when_no_order_is_set_in_c
 
     public function test_sidebar_is_ordered_by_priority_when_priority_is_set_in_config()
     {
-        Config::set('hyde.documentationPageOrder', [
+        Config::set('docs.sidebar_order', [
             'charlie',
             'bravo',
             'alpha',
@@ -127,14 +127,14 @@ public function test_sidebar_item_priority_set_in_config_overrides_front_matter(
             (new ConvertsArrayToFrontMatter)->execute(['priority' => 25])
         );
 
-        Config::set('hyde.documentationPageOrder', ['foo']);
+        Config::set('docs.sidebar_order', ['foo']);
 
         $this->assertEquals(25, DocumentationSidebarService::get()->first()->priority);
     }
 
     public function test_sidebar_priorities_can_be_set_in_both_front_matter_and_config()
     {
-        Config::set('hyde.documentationPageOrder', [
+        Config::set('docs.sidebar_order', [
             'first',
             'third',
             'second',

tests/Feature/Services/HasConfigurableMarkdownFeaturesTest.php

@@ -95,7 +95,7 @@ public function test_has_features_array_can_enable_permalinks()
     // Test that method canEnablePermalinks is automatically for DocumentationPages
     public function test_has_features_array_can_enable_permalinks_auto()
     {
-        Config::set('hyde.documentationPageTableOfContents.enabled', true);
+        Config::set('docs.table_of_contents.enabled', true);
         $this->sourceModel = DocumentationPage::class;
 
         $this->assertTrue($this->canEnablePermalinks());

tests/Feature/StaticPageBuilderTest.php

@@ -106,7 +106,7 @@ public function test_creates_custom_documentation_directory()
     {
         $page = new DocumentationPage([], '# Body', 'Title', 'foo');
 
-        Config::set('hyde.docsDirectory', 'docs/foo');
+        Config::set('docs.output_directory', 'docs/foo');
 
         new StaticPageBuilder($page, true);