From 3a607bae87691b198afd197ecd18c99bd3433385 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Fri, 5 Apr 2024 10:04:56 +1300 Subject: [PATCH] MNT Add documentation linting (#271) * MNT Add documentation linting * DOC Fix linting issues in docs --- .doclintrc | 1 + composer.json | 10 ++++++++-- docs/en/01_basic_usage.md | 5 +---- docs/en/02_configuration.md | 8 ++++---- docs/en/index.md | 12 ++++++------ docs/en/userguide/02_work_with_link_field.md | 12 ++++++------ docs/en/userguide/index.md | 3 ++- 7 files changed, 28 insertions(+), 23 deletions(-) create mode 100644 .doclintrc diff --git a/.doclintrc b/.doclintrc new file mode 100644 index 00000000..a6b65270 --- /dev/null +++ b/.doclintrc @@ -0,0 +1 @@ +docs/en/ diff --git a/composer.json b/composer.json index f40d193d..5c2a51cb 100644 --- a/composer.json +++ b/composer.json @@ -24,8 +24,9 @@ "silverstripe/frameworktest": "^1", "dnadesign/silverstripe-elemental": "^5", "silverstripe/recipe-testing": "^3", - "squizlabs/php_codesniffer": "^3", "silverstripe/standards": "^1", + "silverstripe/documentation-lint": "^1", + "squizlabs/php_codesniffer": "^3", "phpstan/extension-installer": "^1.3" }, "autoload": { @@ -45,5 +46,10 @@ ] }, "minimum-stability": "dev", - "prefer-stable": true + "prefer-stable": true, + "config": { + "allow-plugins": { + "dealerdirect/phpcodesniffer-composer-installer": true + } + } } diff --git a/docs/en/01_basic_usage.md b/docs/en/01_basic_usage.md index 9174f355..eda57d21 100644 --- a/docs/en/01_basic_usage.md +++ b/docs/en/01_basic_usage.md @@ -59,7 +59,7 @@ class MyModel extends DataObject [ LinkField::create('HasOneLink'), MultiLinkField::create('HasManyLinks'), - ], + ] ); return $fields; @@ -79,8 +79,6 @@ If you have multiple `has_many` relations on the same class, they should all poi ```php namespace App\Model; -use SilverStripe\LinkField\Form\LinkField; -use SilverStripe\LinkField\Form\MultiLinkField; use SilverStripe\LinkField\Models\Link; use SilverStripe\ORM\DataObject; @@ -117,7 +115,6 @@ class MyModel extends DataObject private static $has_many = [ 'HasManyLinks' => Link::class . '.Owner', ]; - // ... public function getCMSCompositeValidator(): CompositeValidator diff --git a/docs/en/02_configuration.md b/docs/en/02_configuration.md index c4f7fd23..6eb6d9e5 100644 --- a/docs/en/02_configuration.md +++ b/docs/en/02_configuration.md @@ -5,7 +5,7 @@ summary: Advanced usage of the Link model and link fields # Configuring links and link fields -## Controlling what type of links can be created in a LinkField +## Controlling what type of links can be created in a link field By default, all [`Link`](api:SilverStripe\LinkField\Models\Link) subclasses can be created by a [`LinkField`](api:SilverStripe\LinkField\Form\LinkField) or [`MultiLinkField`](api:SilverStripe\LinkField\Form\MultiLinkField). This includes any custom `Link` subclasses defined in your project or via a third party module. @@ -57,7 +57,7 @@ class MyModel extends DataObject [ LinkField::create('EmailLink')->setAllowedTypes([EmailLink::class]), MultiLinkField::create('LinkList')->setAllowedTypes([SiteTreeLink::class, EmailLink::class]), - ], + ] ); return $fields; } @@ -90,7 +90,7 @@ class MyModel extends DataObject [ LinkField::create('Link')->setExcludeLinkTextField(true), MultiLinkField::create('LinkList')->setExcludeLinkTextField(true), - ], + ] ); return $fields; } @@ -101,7 +101,7 @@ class MyModel extends DataObject You can customise the position of the link type in the menu by setting the the [`menu_priority`](api:SilverStripe\LinkField\Models\Link->menu_priority) configuration property. The priority is in ascending order (i.e. a link with a lower priority value will be displayed higher in the list). -You can also set an icon that will correspond to a specific type of link by setting the value of the [`icon`](api:SilverStripe\LinkField\Models\Link->icon) configuration property. The value of this configuration corresponds to the css class of the icon to be used. +You can also set an icon that will correspond to a specific type of link by setting the value of the [`icon`](api:SilverStripe\LinkField\Models\Link->icon) configuration property. The value of this configuration corresponds to the CSS class of the icon to be used. > [!TIP] > You can find the set of available icons in the [pattern library](https://silverstripe.github.io/silverstripe-pattern-lib/?path=/story/admin-icons--icon-reference). diff --git a/docs/en/index.md b/docs/en/index.md index 3b6254b2..e6fdaf75 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -6,14 +6,14 @@ icon: link # Linkfield -Make sure that your SilverStripe CMS installation has [`silverstripe/linkfield`](https://github.com/silverstripe/silverstripe-linkfield/) installed. +Make sure that your Silverstripe CMS installation has [`silverstripe/linkfield`](https://github.com/silverstripe/silverstripe-linkfield/) installed. This module provides a Link model and CMS interface for managing different types of links. Including: -* Emails -* External links -* Links to pages within the CMS -* Links to assets within the CMS -* Phone numbers +- Emails +- External links +- Links to pages within the CMS +- Links to assets within the CMS +- Phone numbers [CHILDREN includeFolders] diff --git a/docs/en/userguide/02_work_with_link_field.md b/docs/en/userguide/02_work_with_link_field.md index 67182808..bba370e2 100644 --- a/docs/en/userguide/02_work_with_link_field.md +++ b/docs/en/userguide/02_work_with_link_field.md @@ -9,15 +9,15 @@ Previous sections provided fundamental knowledge for creating links. In contrast The LinkField module offers two primary types of fields: one for managing a single link and the other for managing multiple links. While there are some differences in how these fields operate, let's first outline the key aspects that are common to both types of fields. - - To view more detailed information or make changes to an existing link, click anywhere on the link details. This opens the modal window where adjustments can be made. If no changes are required, you can simply close the modal window. +- To view more detailed information or make changes to an existing link, click anywhere on the link details. This opens the modal window where adjustments can be made. If no changes are required, you can simply close the modal window. - - Once a new link is created, basic information about it will be displayed in the Link field. +- Once a new link is created, basic information about it will be displayed in the Link field. - - Any information entered is automatically saved upon the creation of a new link or when you update the link data. +- Any information entered is automatically saved upon the creation of a new link or when you update the link data. - - To publish links, you need to publish a page or data object using the link field. +- To publish links, you need to publish a page or data object using the link field. - - Once created, you can modify the link type. To change a link to a different type, you must delete the existing link and create a new one. +- Once created, you can modify the link type. To change a link to a different type, you must delete the existing link and create a new one. ## Disabled or read-only links @@ -62,7 +62,7 @@ You can remove an existing link by clicking on the "Archive" button. ![A screenshot of the multilink field](./_images/delete_button.png) -## Version history +## Version history Link Field includes versioning support, meaning any changes made are recorded in the change history. Additionally, a badge will appear to indicate interference whenever modifications are made. diff --git a/docs/en/userguide/index.md b/docs/en/userguide/index.md index c933a9e0..f1d8d52e 100644 --- a/docs/en/userguide/index.md +++ b/docs/en/userguide/index.md @@ -6,8 +6,9 @@ summary: How to use the Link Field module to manage links in the CMS. # Managing links in the CMS ## Before we begin +> > [!IMPORTANT] -> Make sure that your SilverStripe CMS installation has the [LinkField](https://packagist.org/packages/silverstripe/linkfield) module installed. +> Make sure that your Silverstripe CMS installation has the [LinkField](https://packagist.org/packages/silverstripe/linkfield) module installed. ## Introduction