Detailed icon functions and icon sets usages (#3027)

Author: adriendupuis

docs/administration/back_office/back_office_elements/custom_icons.md

@@ -15,6 +15,8 @@ ibexa:
             content_type:
                 article:
                     thumbnail: /assets/images/custom_icon.svg#custom
+                category:
+                    thumbnail: /bundles/ibexaadminuiassets/vendors/ids-assets/dist/img/all-icons.svg#folder
 ```
 
 Place the icon in `public/assets/images` and run `yarn encore <dev|prod>` after adding it.
@@ -23,13 +25,15 @@ Place the icon in `public/assets/images` and run `yarn encore <dev|prod>` after
 
     To ensure proper display in the back office, all icons should have SVG format with `symbol`.
 
-If you want to configure icons per SiteAccess, see [Icon sets](#icon-sets).
+Use the [scope](multisite_configuration.md#scope) if you want different icons for different SiteAccesses.
 
-To see more configuration options, see [the icon reference](icon_twig_functions.md).
+To see more Admin UI's `ids-assets` icons, see [the icon reference](icon_twig_functions.md#icons-reference).
 
 ### Access icons in Twig templates
 
-Content type icons are accessible in Twig templates via the `ibexa_content_type_icon` function.
+#### Content type icons
+
+Content type icons are accessible in Twig templates via the [`ibexa_content_type_icon()` function](icon_twig_functions.md#ibexa_content_type_icon).
 It requires content type identifier as an argument. The function returns the path to a content type icon.
 
 ```twig
@@ -38,6 +42,10 @@ It requires content type identifier as an argument. The function returns the pat
 </svg>
 ```
 
+#### UI Icons
+
+User interface icons are accessible with [`ibexa_icon_path()` function](icon_twig_functions.md#ibexa_icon_path). The function returns a path from an icon identifier and an [icon set](#icon-sets) identifier arguments.
+
 ### Access icons in JavaScript
 
 Content types icons configuration is stored in a global object: `ibexa.adminUiConfig.contentTypes`.
@@ -89,7 +97,9 @@ The following example from the `alert.js` file shows configuration for icons in
 - `name` - the path is generated inside the component provided you use icon from the system
 - `extraClasses` - additional CSS classes, use to set for example, icon size.
 
-## Icon sets
+## Customize UI icons
+
+### Icon sets
 
 You can configure icon sets to be used per SiteAccess:
 
@@ -103,3 +113,11 @@ ibexa:
                     additional_icons: /assets/images/icons/additional_icons.svg
                 default_icon_set: my_icons
 ```
+
+The icon sets are used by [`ibexa_icon_path()` Twig function](icon_twig_functions.md#ibexa_icon_path).
+
+- If you change the `default_icon_set` from one SiteAccess to another, `ibexa_icon_path(icon)` without `set` argument targets icons from different set files
+- If you change the file path of an icon set from one SiteAccess to another, `ibexa_icon_path(icon, set)` with the same `set` argument targets icons from different set files
+
+The built-in default icon set is `ids-assets` (corresponding to `/bundles/ibexaadminuiassets/vendors/ids-assets/dist/img/all-icons.svg`).
+To see the icons available in this set, see [the icon reference](icon_twig_functions.md#icons-reference).

docs/templating/twig_function_reference/icon_twig_functions.md

@@ -6,14 +6,14 @@ month_change: false
 
 # Icon Twig functions
 
-### `ibexa_icon_path()`
+## `ibexa_icon_path()`
 
 `ibexa_icon_path()` generates a path to the selected icon from an [icon set](custom_icons.md#icon-sets).
 
-|Argument|Type|Description|
-|------|------|------|
-|`icon`|`string`|Identifier of an icon in the icon set.|
-|`set`|`string`|Identifier of the configured icon set. If empty, the default icon set is used.|
+| Argument | Type     | Description                                                                    |
+|----------|----------|--------------------------------------------------------------------------------|
+| `icon`   | `string` | Identifier of an icon in the icon set.                                         |
+| `set`    | `string` | Identifier of the configured icon set. If empty, the default icon set is used. |
 
 ```html+twig
 <svg class="ibexa-icon ibexa-icon--medium ibexa-icon--light">
@@ -23,7 +23,7 @@ month_change: false
 
 The icons can be displayed in different colors and sizes.
 
-#### Icon color variants
+### Icon color variants
 
 By default, the icon inherits the [`fill`](https://developer.mozilla.org/en-US/docs/Web/CSS/fill) attribute from the parent element.
 You can change it by using one of the available CSS modifiers:
@@ -42,7 +42,7 @@ You can change it by using one of the available CSS modifiers:
 </svg>
 ```
 
-#### Icon size variants
+### Icon size variants
 
 The default icon size in the back office is `32px`.
 To change the default size, in the template add the modifier to the class name.
@@ -66,7 +66,7 @@ The list of available icon sizes:
 |`--large`|`48px`|
 |`--extra-large`|`64px`|
 
-#### Icons reference
+### Icons reference
 
 The following icons are available out-of-the-box:
 
@@ -604,3 +604,12 @@ The following icons are available out-of-the-box:
 | ![zoom-in](img/icons/zoom-in.svg.png) | `zoom-in` |
 | ![zoom-out](img/icons/zoom-out.svg.png) | `zoom-out` |
 
+## `ibexa_content_type_icon()`
+
+`ibexa_content_type_icon()` generates a path to a content type icon.
+
+| Argument       | Type     | Description              |
+|----------------|----------|--------------------------|
+| `content_type` | `string` | Content type identifier. |
+
+See [Customize content type icons](custom_icons.md#customize-content-type-icons) to associate icons to content types.