Merge branch '3.2' into 3

.doclintrc

@@ -0,0 +1 @@
+docs/en/

composer.json

@@ -22,7 +22,8 @@
         "phpunit/phpunit": "^9.6",
         "squizlabs/php_codesniffer": "^3",
         "silverstripe/standards": "^1",
-        "phpstan/extension-installer": "^1.3"
+        "phpstan/extension-installer": "^1.3",
+        "silverstripe/documentation-lint": "^1"
     },
     "suggest": {
         "symbiote/silverstripe-gridfieldextensions": "Allows sorting of TaxonomyTerm objects via drag-and-drop",
@@ -35,7 +36,11 @@
             "SilverStripe\\Taxonomy\\Tests\\Behat\\Context\\": "tests/behat/src/"
         }
     },
-    "extra": [],
+    "config": {
+        "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        }
+    },
     "minimum-stability": "dev",
     "prefer-stable": true
 }

docs/en/01_basic_usage.md

@@ -0,0 +1,78 @@
+---
+title: Basic usage
+summary: How to set up your taxonomy relations and fields
+---
+
+# Basic usage
+
+The main model you'll be interacting with is [`TaxonomyTerm`](api:SilverStripe\Taxonomy\TaxonomyTerm). This class represents the actual taxonomy terms you will apply to your data.
+
+A taxonomy is of extremely limited use by itself. To make use of it, you need to associate it with
+`DataObject` models in your site.
+
+To add the the ability to associate a model with `TaxonomyTerm`, you need to add the many-many relation:
+
+```php
+namespace App\Model;
+
+use SilverStripe\Forms\TreeMultiselectField;
+use SilverStripe\ORM\DataObject;
+use SilverStripe\Taxonomy\TaxonomyTerm;
+
+class MyModel extends DataObject
+{
+    // ...
+    private static $many_many = [
+        'Terms' => TaxonomyTerm::class,
+    ];
+
+    public function getCMSFields()
+    {
+        $fields = parent::getCMSFields();
+        // ...
+        $fields->addFieldToTab('Root.Main', TreeMultiselectField::create(
+            'Terms',
+            $this->fieldLabel('Terms'),
+            TaxonomyTerm::class
+        ));
+        return $fields;
+    }
+}
+```
+
+Run a `dev/build?flush=all` and you'll be able to add taxonomy terms to your record - but now you need to create some terms! See [the userhelp documentation](https://userhelp.silverstripe.org/en/optional_features/taxonomies/) for information about functionality from a content author perspective.
+
+## Filtering by type
+
+If you have implemented taxonomy types, you can filter them to ensure that only taxonomy terms of a given type or types can be selected.
+This can be useful, for example, if you want to separate your terms between files/images/documents and CMS pages.
+
+> [!WARNING]
+> This relies on `TaxonomyType` records which have specific names being set up in the CMS.
+> You will need to coordinate with content authors to ensure these are always available, or else
+> ensure they are created by default by [populating defaults](https://docs.silverstripe.org/en/developer_guides/model/how_tos/dynamic_default_fields/)
+> and ensure they cannot be deleted by [implementing an Extension](https://docs.silverstripe.org/en/developer_guides/extending/extensions/)
+> with the `canDelete()` method.
+
+To implement this filtering, call [`TreeMultiselectField::setFilterFunction()`](api:SilverStripe\Forms\TreeMultiselectField::setFilterFunction()) with the filtering logic:
+
+```php
+use SilverStripe\Forms\TreeMultiselectField;
+use SilverStripe\Taxonomy\TaxonomyTerm;
+use SilverStripe\Taxonomy\TaxonomyType;
+
+/** @var TreeMultiselectField $treeField */
+$typeID = TaxonomyType::get()->find('Name', 'CMS Page')?->ID;
+$treeField->setFilterFunction(fn (TaxonomyTerm $term) => $term->TypeID === $typeID);
+```
+
+## Showing taxonomy terms
+
+So you've got a set of terms associated with a page, and you want to show them on your site. You can loop through them
+like any other relation:
+
+```ss
+<% loop $Terms %>
+    <span class="tag">$Name</span>
+<% end_loop %>
+```

docs/en/index.md

@@ -0,0 +1,13 @@
+---
+title: Taxonomies
+summary: Provides the capability to add and edit simple taxonomies for categorising data
+icon: link
+---
+
+# Taxonomies
+
+Make sure that your Silverstripe CMS installation has [`silverstripe/taxonomy`](https://github.com/silverstripe/silverstripe-taxonomy/) installed.
+
+This module provides a "Taxonomies" section in the CMS, and a couple of `DataObject` models.
+
+[CHILDREN includeFolders]

docs/en/userguide/index.md

@@ -5,44 +5,44 @@ summary: Add and edit simple taxonomies in the CMS.
 
 # Creating and using taxonomies
 
-## In this section:
+## In this section
 
-* Taxonomy usage
-* Taxonomy terms and types
-* Taxonomy creation and removal
-* Permissions
+- Taxonomy usage
+- Taxonomy terms and types
+- Taxonomy creation and removal
+- Permissions
 
-## Before we begin:
+## Before we begin
 
-* Make sure you have the SilverStripe [taxonomy](http://addons.silverstripe.org/add-ons/silverstripe/taxonomy) module installed
+- Make sure you have the Silverstripe [taxonomy](http://addons.silverstripe.org/add-ons/silverstripe/taxonomy) module installed
 
-# Taxonomy usage
+## Taxonomy usage
 
 This module provides a raw skeleton for maintaining taxonomies in the CMS. Taxonomies are used to group content, making it easy to find related pieces of information. By default, the module provides the interface described below to create and manage taxonomies, using Taxonomy Terms and Taxonomy Types.
 
-## Taxonomy terms and types
+### Taxonomy terms and types
 
 The Taxonomy Term is the equivalent of the taxonomy itself - it serves to provide it's name, and as a holder of all the taxonomy's types. For example, a taxonomy term called 'News' could have multiple taxonomy types such as 'National', 'International', and 'Sport'. These help make your content easier to find by refining the focus.
 
-## Taxonomy creation
+### Taxonomy creation
 
-To create a taxonomy, navigate to the **_Taxonomies_** section.
+To create a taxonomy, navigate to the "Taxonomies" section.
 
-The list that appears contains all existing taxonomies - there could be many in parallel. If the list is empty, you will want to create a Taxonomy Type first. To do so, navigate to the **_Taxonomy Types_** tab, click **_Add Taxonomy Type_**, specify the name (e.g. "News") and click **_Create_**.
+The list that appears contains all existing taxonomies - there could be many in parallel. If the list is empty, you will want to create a Taxonomy Type first. To do so, navigate to the "Taxonomy Types" tab, click "Add Taxonomy Type", specify the name (e.g. "News") and click "Create".
 
-To create first layer of terms within the taxonomy, switch to the **_Taxonomy Terms_** tab. Click **_Add Taxonomy Term_** and this time create "National". Switch to the **_Children_** tab, and nest another term underneath: (e.g. "Weather"). You have just
+To create first layer of terms within the taxonomy, switch to the "Taxonomy Terms" tab. Click "Add Taxonomy Term" and this time create "National". Switch to the "Children" tab, and nest another term underneath: (e.g. "Weather"). You have just
 created a three-level hierarchy of "News > National > Weather".
 
 ![Example of taxonomy](_images/taxonomies-terms.jpg)
 
 You can easily navigate around the hierarchy by using breadcrumbs at the top as you would with other areas in
-SilverStripe CMS.
+Silverstripe CMS.
 
-## Taxonomy removal
+### Taxonomy removal
 
-The taxonomies can be recursively removed. To remove an entire taxonomy, you can click the button **_More options_** which is shown as an ellipses icon and choose **_Delete_**. All terms belonging to it will be removed.
+The taxonomies can be recursively removed. To remove an entire taxonomy, you can click the button "More options" which is shown as an ellipses icon and choose "Delete". All terms belonging to it will be removed.
 
-You can also remove parts of the taxonomy tree - just descend into the children terms, and use the **_More options_** button next to
+You can also remove parts of the taxonomy tree - just descend into the children terms, and use the "More options" button next to
 the top-level item of the subtree to be removed.
 
 ## Permissions
@@ -51,6 +51,6 @@ the top-level item of the subtree to be removed.
 
 Site administrator can specify permissions around taxonomies. There are three permissions that can be set on groups:
 
-* **_Create a taxonomy term_**: allows adding new terms to existing taxonomies.
-* **_Delete a taxonomy term and all nested terms_**: allows to delete items recursively.
-* **_Edit a taxonomy term_**: allows members of the group to update the taxonomy details.
+- "Create a taxonomy term": allows adding new terms to existing taxonomies.
+- "Delete a taxonomy term and all nested terms": allows to delete items recursively.
+- "Edit a taxonomy term": allows members of the group to update the taxonomy details.