include_file VS include_code

Author: adriendupuis

docs/administration/recent_activity/recent_activity.md

@@ -85,6 +85,9 @@ It uses the default `admin` user that has a [permission](#permission-and-securit
 ```php hl_lines="34-38"
 [[= include_file('code_samples/recent_activity/src/Command/MonitorRecentContentCreationCommand.php') =]]
 ```
+```php hl_lines="34-38"
+[[= include_code('code_samples/recent_activity/src/Command/MonitorRecentContentCreationCommand.php') =]]
+```
 
 ```console
 % php bin/console app:monitor-content-creation
@@ -145,6 +148,9 @@ This event has the information needed by a log entry (see details after the exam
 ```php
 [[= include_file('code_samples/recent_activity/src/EventSubscriber/MyFeatureEventSubscriber.php') =]]
 ```
+```php
+[[= include_code('code_samples/recent_activity/src/EventSubscriber/MyFeatureEventSubscriber.php') =]]
+```
 
 `ActivityLogService::build()` function returns an `Ibexa\Contracts\ActivityLog\Values\CreateActivityLogStruct` which can then be passed to `ActivityLogService::save`.
 
@@ -192,6 +198,9 @@ In the following example, several actions are logged into one context group, eve
 ``` php
 [[= include_file('code_samples/recent_activity/src/Command/ActivityLogContextTestCommand.php', 46, 66, remove_indent=True) =]]
 ```
+``` php
+[[= include_code('code_samples/recent_activity/src/Command/ActivityLogContextTestCommand.php', 47, 66, remove_indent=True) =]]
+```
 
 Context groups can't be nested.
 If a new context is prepared when a context is already grouping log entries, this new context is ignored.
@@ -229,12 +238,18 @@ It can be used during development as a fallback for classes that aren't mapped y
 ``` twig
 [[= include_file('code_samples/recent_activity/templates/themes/admin/activity_log/ui/default.html.twig') =]]
 ```
+``` twig
+[[= include_code('code_samples/recent_activity/templates/themes/admin/activity_log/ui/default.html.twig') =]]
+```
 
 Here is an example of a `ClassNameMapperInterface` associating the class `App\MyFeature\MyFeature` with the identifier `my_feature`:
 
 ``` php
 [[= include_file('code_samples/recent_activity/src/ActivityLog/ClassNameMapper/MyFeatureNameMapper.php') =]]
 ```
+``` php
+[[= include_code('code_samples/recent_activity/src/ActivityLog/ClassNameMapper/MyFeatureNameMapper.php') =]]
+```
 
 This mapper also provides a translation for the class name in the **Filters** menu.
 This translation can be extracted with `php bin/console jms:translation:extract en --domain=ibexa_activity_log --dir=src --output-dir=translations`.
@@ -244,12 +259,18 @@ To be taken into account, this mapper must be registered as a service:
 ``` yaml
 [[= include_file('code_samples/recent_activity/config/append_to_services.yaml') =]]
 ```
+``` yaml
+[[= include_code('code_samples/recent_activity/config/append_to_services.yaml') =]]
+```
 
 Here is an example of a `PostActivityListLoadEvent` subscriber which loads the related object when it's an `App\MyFeature\MyFeature`, and attaches it to the log entry:
 
 ``` php
 [[= include_file('code_samples/recent_activity/src/EventSubscriber/MyFeaturePostActivityListLoadEventSubscriber.php') =]]
 ```
+``` php
+[[= include_code('code_samples/recent_activity/src/EventSubscriber/MyFeaturePostActivityListLoadEventSubscriber.php') =]]
+```
 
 The following template is made to display the object of `App\MyFeature\MyFeature` (now identified as `my_feature`) when the action is `simulate`,
 so, it's named in `templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig`.
@@ -258,6 +279,9 @@ Thanks to the previous subscriber, the related object is available at display ti
 ``` twig
 [[= include_file('code_samples/recent_activity/templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig') =]]
 ```
+``` twig
+[[= include_code('code_samples/recent_activity/templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig') =]]
+```
 
 ## REST API
 

docs/api/rest_api/rest_api_usage/rest_requests.md

@@ -171,12 +171,18 @@ This script:
     ``` php
     [[= include_file('code_samples/api/rest_api/create_image.xml.php', 0, None, '    ') =]]
     ```
+    ``` php
+    [[= include_code('code_samples/api/rest_api/create_image.xml.php', 1, None, 1) =]]
+    ```
 
 === "JSON"
 
     ``` php
     [[= include_file('code_samples/api/rest_api/create_image.json.php', 0, None, '    ') =]]
     ```
+    ``` php
+    [[= include_code('code_samples/api/rest_api/create_image.json.php', indent_level=1) =]]
+    ```
 
 ### Search (`/views`)
 

docs/search/search_api.md

@@ -34,6 +34,15 @@ The following command takes the content type identifier as an argument and lists
 [[= include_file('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 32, 48) =]]
 [[= include_file('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 48, 49) =]]
 ```
+``` php hl_lines="14 16"
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 5, 7) =]]
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 18, 19) =]]
+    // ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 33, 48) =]]
+[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 49, 49) =]]
+```
 
 [`SearchService::findContentInfo`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-SearchService.html#method_findContentInfo) (line 16)
 retrieves [`ContentInfo`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Persistence-Content-ContentInfo.html) objects of the found content items.
@@ -124,6 +133,14 @@ For example, the following command lists all content items under the specified p
 // ...
 [[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 19, 21) =]][[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 33, 53) =]]
 ```
+``` php hl_lines="15-18"
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 5, 9) =]]
+
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 20, 21) =]]
+[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 34, 53) =]]
+```
 
 The same Filter can be applied to find locations instead of content items, for example:
 
@@ -133,6 +150,14 @@ The same Filter can be applied to find locations instead of content items, for e
 [[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 19, 21) =]]// ...
 [[= include_file('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 33, 53) =]]
 ```
+``` php hl_lines="20"
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 5, 9) =]]
+
+[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 20, 21) =]]
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 34, 53) =]]
+```
 
 !!! caution
 
@@ -186,6 +211,12 @@ For example, in the code below, `locationId` is provided to list all children of
 [[= include_file('code_samples/api/public_php_api/src/Controller/CustomController.php', 4, 12) =]]    // ...
 [[= include_file('code_samples/api/public_php_api/src/Controller/CustomController.php', 16, 32) =]]
 ```
+``` php hl_lines="22-24"
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Controller/CustomController.php', 5, 12) =]]
+    // ...
+[[= include_code('code_samples/api/public_php_api/src/Controller/CustomController.php', 17, 32) =]]
+```
 
 The rendering of results is then relegated to [templates](templates.md) (lines 22-24).
 
@@ -196,6 +227,12 @@ When using Repository filtering, provide the results of `ContentService::find()`
 [[= include_file('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 4, 12) =]]    // ...
 [[= include_file('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 16, 31) =]]
 ```
+``` php hl_lines="19"
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 5, 12) =]]
+    // ...
+[[= include_code('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 17, 31) =]]
+```
 
 ### Paginate search results
 
@@ -206,12 +243,21 @@ To paginate search or filtering results, it's recommended to use the [Pagerfanta
 [[= include_file('code_samples/api/public_php_api/src/Controller/PaginationController.php', 8, 15) =]]    // ...
 [[= include_file('code_samples/api/public_php_api/src/Controller/PaginationController.php', 19, 39) =]]
 ```
+``` php
+// ...
+[[= include_code('code_samples/api/public_php_api/src/Controller/PaginationController.php', 9, 15) =]]
+    // ...
+[[= include_code('code_samples/api/public_php_api/src/Controller/PaginationController.php', 20, 39) =]]
+```
 
 Pagination can then be rendered for example using the following template:
 
 ``` html+twig
 [[= include_file('code_samples/api/public_php_api/templates/themes/standard/full/custom_pagination.html.twig') =]]
 ```
+``` html+twig
+[[= include_code('code_samples/api/public_php_api/templates/themes/standard/full/custom_pagination.html.twig') =]]
+```
 
 For more information and examples, see [PagerFanta documentation](https://www.babdev.com/open-source/packages/pagerfanta/docs/2.x/usage).
 
@@ -244,6 +290,12 @@ You can do it using logical operators: `LogicalAnd`, `LogicalOr`, and `LogicalNo
 [[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 44, 49) =]][[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 53, 54) =]]
 [[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 60, 65) =]]
 
+```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 45, 49) =]]
+[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 54, 54) =]]
+
+[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 61, 65) =]]
 ```
 
 This example takes three parameters from a command — `$text`, `$contentTypeId`, and `$locationId`.
@@ -259,6 +311,9 @@ that doesn't belong to the provided Section:
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 46, 54) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 47, 54) =]]
+```
 
 ### Combine independent Criteria
 
@@ -292,6 +347,9 @@ For example, to order search results by their publication date, from oldest to n
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 55, 59) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 56, 59) =]]
+```
 
 !!! tip
 
@@ -310,6 +368,9 @@ To do this, you use of the query's `$aggregations` property:
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 30, 35) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 31, 35) =]]
+```
 
 The name of the aggregation must be unique in the given query.
 
@@ -318,12 +379,18 @@ Access the results by using the `get()` method of the aggregation:
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 39, 40) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 40, 40) =]]
+```
 
 Aggregation results contain the name of the result and the count of found items:
 
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 42, 45) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 43, 45) =]]
+```
 
 With field aggregations you can group search results according to the value of a specific field.
 In this case the aggregation takes the content type identifier and the field identifier as parameters.
@@ -333,13 +400,19 @@ The following example creates an aggregation named `selection` that groups resul
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 35, 36) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 36, 36) =]]
+```
 
 With term aggregation you can define additional limits to the results.
 The following example limits the number of terms returned to 5 and only considers terms that have 10 or more results:
 
 ``` php
 [[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 30, 33) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 31, 33) =]]
+```
 
 To use a range aggregation, you must provide a `ranges` array containing a set of `Range` objects that define the borders of the specific range sets.
 
@@ -396,6 +469,9 @@ This example shows a minimal embedding query executed directly through the searc
 ``` php hl_lines="38-39 41-47 49"
 [[= include_file('code_samples/api/public_php_api/src/Command/FindByTaxonomyEmbeddingCommand.php') =]]
 ```
+``` php hl_lines="38-39 41-47 49"
+[[= include_code('code_samples/api/public_php_api/src/Command/FindByTaxonomyEmbeddingCommand.php') =]]
+```
 
 For more information, see [Embeddings reference](embeddings_reference.md).
 
@@ -414,6 +490,11 @@ For a list of supported Criteria and Sort Clauses, see [Search in trash referenc
 [[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 4, 6) =]]//...
 [[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 35, 42) =]]
 ```
+``` php
+[[= include_code('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 5, 6) =]]
+//...
+[[= include_code('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 36, 42) =]]
+```
 
 !!! caution