Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor configuration to use snake_case for all options, and extract documentation settings to own file #444

Merged
merged 17 commits into from
May 22, 2022
Merged

Refactor configuration to use snake_case for all options, and extract documentation settings to own file #444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
4ba0ef0
Rename config keys to use snake_case
caendesilva May 22, 2022
9507514
Remove "Asset Locations and Versions" config setting
caendesilva May 22, 2022
2e89065
Change config keys to lowercase
caendesilva May 22, 2022
8ebdef3
Remove unused "smoothPageScrolling" config option
caendesilva May 22, 2022
ea5d220
Fix wrong variable name causing TOC not to show
caendesilva May 22, 2022
62bc5c3
Change config key case to snake_case
caendesilva May 22, 2022
807d085
Update config keys to snake_case
caendesilva May 22, 2022
92b9ae5
Extract documentation configuration options to docs.php
caendesilva May 22, 2022
f578855
Use the snake_case config format
caendesilva May 22, 2022
668c2be
Use the snake_case config format
caendesilva May 22, 2022
7531b44
Use the snake_case config format
caendesilva May 22, 2022
0105243
Use the snake_case config format
caendesilva May 22, 2022
acc274a
Deprecate YAML file
caendesilva May 22, 2022
2cef183
Apply fixes from StyleCI
StyleCIBot May 22, 2022
c2df671
Merge pull request #443 from hydephp/analysis-bQp4xl
May 22, 2022
5334c89
Add deprecation notice
caendesilva May 22, 2022
a2fe955
Merge branch 'refactor-configs' of github.com:hydephp/framework into …
caendesilva May 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .github/dev-docs/RELEASE-NOTES-DRAFT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# 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.

The authors.yml has been deprecated, and will be refactored in an upcoming release.
25 changes: 13 additions & 12 deletions .github/dev-docs/documentation-pages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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._

Expand Down Expand Up @@ -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
'docsDirectory' => 'docs' // Default
'docsDirectory' => '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
'docsSidebarHeaderTitle' => 'API Documentation',
'title' => 'API Documentation',
```

### Sidebar page order
Expand All @@ -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
'documentationPageOrder' => [
'sidebar_order' => [
'readme',
'installation',
'getting-started',
Expand All @@ -196,14 +196,15 @@ 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
'documentationPageTableOfContents' => [
'table_of_contents' => [
'enabled' => true,
'minHeadingLevel' => 2,
'maxHeadingLevel' => 4,
'smoothPageScrolling' => true,
'min_heading_level' => 2,
'max_heading_level' => 4,
'smooth_page_scrolling' => true,
],
```
2 changes: 1 addition & 1 deletion .github/dev-docs/managing-assets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ But as always with Hyde, you can customize everything if you want to.

Hyde ships with a complete frontend where base styles and scripts are included through [HydeFront](https://github.com/hydephp/hydefront) which adds accessibility and mobile support as well as interactions for dark mode switching and navigation and sidebar interactions.

HydeFront is split into two files, `hyde.css` and `hyde.js`. These are loaded in the default Blade views using the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/hydefront). This is the recommended way to load the base styles as the [Hyde Framework](https://github.com/hydephp/framework) automatically makes sure that the correct HydeFront version for the current version of Hyde is loaded. You can disable the CDN in the `config/hyde.php` file by setting `'loadHydeAssetsUsingCDN'` to `false`.
HydeFront is split into two files, `hyde.css` and `hyde.js`. These are loaded in the default Blade views using the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/hydefront). This is the recommended way to load the base styles as the [Hyde Framework](https://github.com/hydephp/framework) automatically makes sure that the correct HydeFront version for the current version of Hyde is loaded. If you don't want to use HydeFribtm you can customize the `styles.blade.php` file.

The bulk of the frontend is built with [TailwindCSS](https://tailwindcss.com/). To get you started, when installing Hyde, all the Tailwind styles you need come precompiled and minified into `_media/app.css`.

Expand Down
82 changes: 82 additions & 0 deletions config/docs.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<?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,
],
];
103 changes: 6 additions & 97 deletions config/hyde.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@

'site_url' => env('SITE_URL', null),

'prettyUrls' => false,
'pretty_urls' => false,

'generateSitemap' => true,
'generate_sitemap' => true,

/*
|--------------------------------------------------------------------------
Expand Down Expand Up @@ -123,27 +123,6 @@
Features::torchlight(),
],

/*
|--------------------------------------------------------------------------
| Asset Locations and Versions
|--------------------------------------------------------------------------
|
| Since v0.15.0, the default Hyde styles are no longer included as
| publishable resources. This is to make updating easier, and to
| reduce complexity. Instead, the assets are loaded through the
| jsDelivr CDN.
|
| The CDN version is defined in the AssetService class,
| but can be changed here to a valid HydeFront tag.
|
| If you load HydeFront through Laravel Mix using the NPM package,
| you should disable the HydeFront CDN feature.
|
*/

'loadHydeAssetsUsingCDN' => true,
// 'cdnVersionOverride' => 'v1.0.0',

/*
|--------------------------------------------------------------------------
| Footer Text
Expand Down Expand Up @@ -178,7 +157,7 @@
|
*/

'navigationMenuLinks' => [
'navigation_menu_links' => [
// [
// 'title' => 'GitHub',
// 'destination' => 'https://github.com/hydephp/hyde',
Expand All @@ -199,43 +178,10 @@
|
*/

'navigationMenuBlacklist' => [
'navigation_menu_blacklist' => [
'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.
|
*/

'docsSidebarHeaderTitle' => $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
*/
'docsDirectory' => 'docs',

/*
|--------------------------------------------------------------------------
| Site Output Directory (Experimental 🧪)
Expand All @@ -249,44 +195,7 @@
|
*/

'siteOutputPath' => 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.
|
*/

'documentationPageOrder' => [
'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.
|
*/

'documentationPageTableOfContents' => [
'enabled' => true,
'minHeadingLevel' => 2,
'maxHeadingLevel' => 4,
'smoothPageScrolling' => true,
],
'site_output_path' => Hyde\Framework\Hyde::path('_site'),

/*
|--------------------------------------------------------------------------
Expand All @@ -298,6 +207,6 @@
|
*/

'warnAboutOutdatedConfig' => true,
'warn_about_outdated_config' => true,

];
4 changes: 2 additions & 2 deletions resources/views/components/docs/labeled-sidebar-navigation-menu.blade.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
<li @class([ 'sidebar-navigation-item' , 'active'=> $item->destination === basename($currentPage)]) role="listitem">
@if($item->destination === basename($currentPage))
<a href="{{ Hyde::pageLink($item->destination . '.html') }}" aria-current="true">{{ $item->label }}</a>
@if(isset($docs->tableOfContents))
@if(isset($page->tableOfContents))
<span class="sr-only">Table of contents</span>
{!! ($docs->tableOfContents) !!}
{!! ($page->tableOfContents) !!}
@endif
@else
<a href="{{ Hyde::pageLink($item->destination . '.html') }}">{{ $item->label }}</a>
Expand Down
4 changes: 2 additions & 2 deletions resources/views/components/docs/sidebar-navigation-menu.blade.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
<a href="{{ Hyde::pageLink($item->destination . '.html') }}" aria-current="true">{{
$item->label }}</a>

@if(isset($docs->tableOfContents))
@if(isset($page->tableOfContents))
<span class="sr-only">Table of contents</span>
{!! ($docs->tableOfContents) !!}
{!! ($page->tableOfContents) !!}
@endif
@else
<a href="{{ Hyde::pageLink($item->destination . '.html') }}">{{ $item->label }}</a>
Expand Down
8 changes: 4 additions & 4 deletions resources/views/layouts/docs.blade.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@
<strong class="mr-auto">
@if(Hyde::docsIndexPath() !== false)
<a href="{{ Hyde::relativeLink(Hyde::docsIndexPath(), $currentPage) }}">
{{ config('hyde.docsSidebarHeaderTitle', 'Documentation') }}
{{ config('docs.title', 'Documentation') }}
</a>
@else
{{ config('hyde.docsSidebarHeaderTitle', 'Documentation') }}
{{ config('docs.title', 'Documentation') }}
@endif
</strong>
@include('hyde::components.navigation.theme-toggle-button')
Expand All @@ -35,10 +35,10 @@
<strong>
@if(Hyde::docsIndexPath() !== false)
<a href="{{ Hyde::relativeLink(Hyde::docsIndexPath(), $currentPage) }}">
{{ config('hyde.docsSidebarHeaderTitle', 'Documentation') }}
{{ config('docs.title', 'Documentation') }}
</a>
@else
{{ config('hyde.docsSidebarHeaderTitle', 'Documentation') }}
{{ config('docs.title', 'Documentation') }}
@endif
</strong>
@include('hyde::components.navigation.theme-toggle-button')
Expand Down
Loading