Co-authored-by: cpaulve-1A <[email protected]…

….com>

feat: re-format documentation notes to be aligned with Github recommendations

README.md

@@ -9,9 +9,11 @@ The **Otter** project is a highly modular framework whose goal is to provide a c
 It is split into several units to cover different aspects of these applications (localization, testing, customization, etc.).
 Also, to customize an application, metadata can be extracted from the application source code and injected into a CMS to manage dynamic configuration.
 
-> **Note**: The full documentation is available [here](./docs/README.md). 
-> 
-> **Note**: A showcase to help you integrate some simple use case is available [here](https://amadeusitgroup.github.io/otter/#/home) 
+> [!TIP]
+> The full documentation is available [here](./docs/README.md).
+
+> [!TIP]
+> A showcase to help you integrate some simple use cases is available [here](https://amadeusitgroup.github.io/otter/#/home)
 
 ## Built With
 
@@ -31,7 +33,8 @@ A new application can be set up with this simple command:
 npm create @o3r my-app
 ```
 
-> **Note**: Please refer to [Otter Get Started](./docs/core/START_NEW_APPLICATION.md) and [Angular Get Started](https://angular.io/guide/setup-local#install-the-angular-cli) for complete documentation.
+> [!TIP]
+> Please refer to [Otter Get Started](./docs/core/START_NEW_APPLICATION.md) and [Angular Get Started](https://angular.io/guide/setup-local#install-the-angular-cli) for complete documentation.
 
 ## Contributing
 
@@ -91,7 +94,7 @@ following products on your development machine:
 * [Node.js](http://nodejs.org), (version `>=18.0.0`)
   * This is used to run tests and generate distributable files. We strongly encourage to use an up-to-date LTS version of Node.js to ensure the support of all the Otter packages.
     Each package comes with a minimum Node.js version range defined in the `engine` property of its package.json file.
-  
+
 * [Yarn](https://yarnpkg.com/lang/en/docs/install/), a Node's Package Manager
   * You can install yarn using NPM manager (coming with Node.js).
     The version of Yarn currently used is embedded in the repository and it can be installed using the provided Node.js [corepack](https://yarnpkg.com/getting-started/install).
@@ -132,7 +135,8 @@ Each module can be built independently thanks to [Nx](https://nx.dev/packages/nx
 yarn nx build core
 ```
 
-> **Note**: Results are put in the `dist` of each module (`packages/@<scope>/<module>/dist`).
+> [!NOTE]
+> Results are put in the `dist` of each module (`packages/@<scope>/<module>/dist`).
 
 #### Running tests locally
 

apps/github-cascading-app/README.md

@@ -60,4 +60,5 @@ The following configurations are available:
 | cascadingBranchesPattern | Pattern determining if the branch is part of the cascading strategy                                                                                                                                           | `^releases?/\\d+\\.\\d+`                                 | `string`   |
 | versionCapturePattern    | Pattern containing a capture to extract the version of a cascading branch                                                                                                                                     | `/((?:0\|[1-9]\\d*)\\.(?:0\|[1-9]\\d*)(?:\\.0-[^ ]+)?)$` | `string`   |
 | bypassReviewers          | Pattern containing a capture to extract the version of a cascading branch                                                                                                                                     | `false`                                                  | `boolean`  |
-> **Note**: The `bypassReviewers` option will require to set the `otter-cascading` bot as **bypass user** to be able to merge the `cascading/*` pull requests.
+> [!IMPORTANT]
+> The `bypassReviewers` option will require to set the `otter-cascading` bot as **bypass user** to be able to merge the `cascading/*` pull requests.

apps/vscode-extension/README.md

@@ -5,7 +5,8 @@ This package contains the Visual Studio Code extension for Otter framework.
 ## Intellisense
 
 In VS Code, you benefit of intellisense for:
- - Configuration metadata tags in the JSDoc (for now, only @o3rWidget and @o3rWidgetParam)
+
+- Configuration metadata tags in the JSDoc (for now, only @o3rWidget and @o3rWidgetParam)
 
 ## Available commands
 
@@ -36,6 +37,7 @@ The following commands are currently available:
 All these commands are also available in the command panel.
 
 The ones which add feature to component are available in the command panel only if the active editor is the component file with some exceptions:
+
 - `Otter: Add theming to component` available when the style file is open
 - `Otter: Add localization key to component` avaibable when the template is open and a text is selected
 
@@ -46,4 +48,5 @@ The ones which add feature to component are available in the command panel only
 | Otter: Extract SCSS property to o3r.variable       | Extract a SCSS property into a o3r.variable                 | Command panel only                              |
 | Otter: Extract all SCSS properties to o3r.variable | Extract all the SCSS properties of a file into o3r.variable | Right-click when selecting code in styling file |
 
-> **Node**: Check [extract styling documentation](https://github.com/AmadeusITGroup/otter/tree/main/docs/vscode-extension/EXTRACT_STYLING.md)
+> [!TIP]
+> Check [extract styling documentation](https://github.com/AmadeusITGroup/otter/tree/main/docs/vscode-extension/EXTRACT_STYLING.md)

docs/api-sdk/COMPOSITION_INHERITANCE.md

@@ -1,15 +1,18 @@
 # Composition and Inheritance
+
 This page refers to the [OpenApi Inheritance feature](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/)
 and the [allOf, oneOf schemes](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
 
 AllOf schema are supported by the generator and will be treated as inheritance or composition depending on the presence of a discriminator property.
 
 ## Composition
+
 An "allOf" schema without a discriminator will be considered as a composition of other models without any hierarchy link.
-This means all the properties of each model will be copied into the model without any reference to the models it is 
+This means all the properties of each model will be copied into the model without any reference to the models it is
 composed of.
 
 For example, the following model
+
 ```yaml
 components:
   schemas:
@@ -33,15 +36,20 @@ components:
             rootCause:
               type: string
 ```
+
 will generate two models:
+
 - BasicErrorModel
+
 ```typescript
 export interface BasicErrorModel {
   message: string;
   code: number;
 }
 ```
+
 - ExtendedErrorModel
+
 ```typescript
 export interface ExtendedErrorModel {
   message: string;
@@ -50,11 +58,12 @@ export interface ExtendedErrorModel {
 }
 ```
 
-## Inheritance:
+## Inheritance
 
 The addition of a discriminator allows a hierarchy between the models and the possibility to identify which child class
 a model can be casted into.
 For example, let's consider a Pet object and its two class child Cat and Dog:
+
 ```yaml
 components:
   schemas:
@@ -118,6 +127,7 @@ It is a bit more tricky to revive the parent model.
 
 In this case, the SDK will try to rely on the discriminator's value and try to map one of the child models. If it fails,
 it will try to revive its own properties.
+
 ```typescript
 export function revivePet<T extends Pet = Pet>(data: any): undefined | T | Cat | Dog {
   if (!data) {return;}
@@ -133,13 +143,15 @@ export function revivePet<T extends Pet = Pet>(data: any): undefined | T | Cat |
 }
 ```
 
-> **Note**: The discriminator needs to be of enum type as the string format would be too generic to map the accepted 
+> [!NOTE]
+> The discriminator needs to be of enum type as the string format would be too generic to map the accepted
 > value to the supported models.
 
 ## Union Type
+
 The oneOf schema is also supported and is handled as an union type.
 
-Instead of considering a generic Pet model and its two children Cat and Dog, let's consider instead that a Pet can be 
+Instead of considering a generic Pet model and its two children Cat and Dog, let's consider instead that a Pet can be
 either a Cat or a Dog.
 
 This time, the specification will be as follows:
@@ -187,6 +199,7 @@ components:
 For this use case, the relation between Pet, Cat and Dog will be a union.
 
 Hence the generated code will be as follows:
+
 ```typescript
 export interface Cat {
   petType: PetTypeEnum;
@@ -205,10 +218,12 @@ export type BreedEnum = 'Dingo' | 'Husky' | 'Retriever' | 'Sheperd';
 export type PetTypeEnum = 'Cat' | 'Dog';
 export type Pet = Cat | Dog;
 ```
-The revival of the Pet is handled the same way as the problem is the same: a discriminator is needed to ensure which 
+
+The revival of the Pet is handled the same way as the problem is the same: a discriminator is needed to ensure which
 model to revive.
 
 >**Note** Just as the inheritance, for a proper revival of the object, the discriminator shall be an enum.
 
 ### Non supported schema type
+
 As of today, the Typescript generator does not support the anyOf and the not schema.

docs/api-sdk/SDK_MODELS_HIERARCHY.md

@@ -49,9 +49,11 @@ export type MyModelCoreIfy<T extends IgnoreEnum<MyModel>> = T & {
 
 ```
 
-> **Info**: The naming convention requires to suffix the core model factory with `CoreIfy`.
+> [!CAUTION]
+> The naming convention requires to suffix the core model factory with `CoreIfy`.
 
-> **Info**: The `IgnoreEnum` helper is used to exclude the enum values (in the base model sub models) from the constraint in case of enum extension.
+> [!NOTE]
+> The `IgnoreEnum` helper is used to exclude the enum values (in the base model sub models) from the constraint in case of enum extension.
 
 And then be used in the SDKs as follows:
 
@@ -65,7 +67,8 @@ export type MyModel = MyModelCoreIfy<BaseModel>;
 export type {BaseModel as  BaseMyModel}; // not required but useful to be used in id generator
 ```
 
-> **Info**: this file should be listed in the `.swagger-codegen-ignore` file to not be regenerated by the swagger generator.
+> [!IMPORTANT]
+> This file should be listed in the `.swagger-codegen-ignore` file to not be regenerated by the swagger generator.
 
 ### Reviver factories
 
@@ -93,7 +96,8 @@ export function reviveMyModelFactory<R extends typeof reviveMyModel>(baseRevive:
 }
 ```
 
-> **Warning**: The usage of `import type` is mandatory for the import of the **base reviver** to avoid bringing an unused revivers in the final application.
+> [!WARNING]
+> The usage of `import type` is mandatory for the import of the **base reviver** to avoid bringing an unused revivers in the final application.
 
 And then be used in the SDKs as follows:
 

docs/apis-manager/API_MANAGER.md

@@ -90,7 +90,8 @@ class MyClass {
 }
 ```
 
-> **Warning** : Do not forget to import the **ApiManagerModule** in you component module
+> [!WARNING]
+> Do not forget to import the **ApiManagerModule** in you component module
 
 ### Enforce custom Api usage
 
@@ -131,7 +132,8 @@ class MyClass {
 }
 ```
 
-> **Note** : Even though the components that you reuse from a library are importing @shared/sdk, the ApiFactoryService will provide at runtime the one that you provided in your app module
+> [!NOTE]
+> Even though the components that you reuse from a library are importing @shared/sdk, the ApiFactoryService will provide at runtime the one that you provided in your app module
 
 ### Override configuration after instantiation
 

docs/components/COMPONENT_STRUCTURE.md

@@ -96,7 +96,7 @@ export interface MyComponentContextInput {
 
   input2: TemplateRef<MyComponentPresContext>;
 }
-  
+
 export interface MyComponentContextOutput {
 
   output1: number;
@@ -125,7 +125,7 @@ export  interface MyComponentPresTranslation extends Translation {
 export  const translations: MyComponentPresTranslation = {
   prop1: 'o3r-my-component-pres.somekey1',
   prop2: 'o3r-my-component-pres.somekey2'
-}; 
+};
 ```
 
 ### Localization (`*.localization.json`)

docs/components/PLACEHOLDERS.md

@@ -17,7 +17,8 @@ The component only has 1 input and supports a *content value*.
 Based on the **id** provided to the placeholder component, it will register itself to the event coming from *
 *placeholderTemplate** and will display the template corresponding to its ID in the store.
 
-> **note**: it is **strongly encouraged** to use the placeholder mechanism in concert with
+> [!IMPORTANT]
+> It is **strongly encouraged** to use the placeholder mechanism in concert with
 > the [Rules Engine](../rules-engine/) following [this documentation](../rules-engine/how-to-use/placeholders.md).
 
 ## How to define a placeholder template
@@ -91,12 +92,13 @@ ex: `assets/placeholders/[LANGUAGE]/myPlaceholder.json`)
 The rules engine service will handle the replacement of `[LANGUAGE]` for you, and when you change language a new call
 will be performed to the new 'translated' URL.
 
-> **Note**: the URL caching mechanism is based on the url NOT 'translated', meaning that if you change from en-GB to
+> [!NOTE]
+> The URL caching mechanism is based on the url NOT 'translated', meaning that if you change from en-GB to
 > fr-FR then you decide to switch back and all the calls will be done again.
 > This behavior is based on the fact that a real user rarely goes back and forth with the language update.
 
-
 ### Dynamic localization
+
 Your second option is to manage your placeholder in a single template and use the dynamic localization mechanism.
 
 In that use case, you can refer to localization keys in your master placeholder template.
@@ -144,15 +146,15 @@ Let's consider what this placeholder would look like if it were completely integ
 
 Then, let's create a new localization key for each of your supported languages:
 
-* en-GB.json
+- en-GB.json
 
 ```json
 {
   "o3r-increment-key": "{increment, plural, =1 {1 second has} other {{{increment}} seconds have}} elapsed since you opened the page"
 }
 ```
 
-* fr-FR.json
+- fr-FR.json
 
 ```json
 {
@@ -215,6 +217,7 @@ Today you cannot only make a reference to a fact with the same name. You also ca
 This means the following is not possible:
 
 ``ruleset.json``
+
 ```json
 {
   "vars": {

docs/core/MODULE.md

@@ -10,7 +10,8 @@ To be considered as an Otter Module, the package need to respect the following g
 - The module should report logs via the Logger exposed by the [@o3r/logging](https://www.npmjs.com/package/@o3r/logging)
 - If the module exposes debug (or configuration) feature, it should be done via the debug interfaces exposed by [@o3r/core](https://www.npmjs.com/package/@o3r/core)
 
-> **Note**: The full list of Otter modules is available on this [page](https://www.npmjs.com/search?q=keywords:otter-module).
+> [!TIP]
+> The full list of Otter modules is available on this [page](https://www.npmjs.com/search?q=keywords:otter-module).
 
 ## Helpers packages
 
@@ -37,7 +38,8 @@ You can also manually create your own module by following the instructions of th
 ### Module development
 
 As indicated in the [definition section](#definition), an Otter module should expose a `ng-add` schematic to allow developers to install the module via the command `ng add <package-name>`.
-> **Note**: Information relative to the `ng-add` schematics is available [here](https://angular.io/cli/add).
+> [!TIP]
+> Information relative to the `ng-add` schematics is available [here](https://angular.io/cli/add).
 
 As all the Otter modules follow the same requirement, the new module can use provided helpers to trigger the installation of other Otter modules, through the `ng-add` schematic of the requested module.
 
@@ -49,7 +51,8 @@ Run the following command in the module where the `ng add` needs to be included:
 ng generate @o3r/core:ng-add-create
 ```
 
-> **Note**: To finish, make sure to run the `build:schematics` script in the process of packaging/publishing the new module.
+> [!IMPORTANT]
+> To finish, make sure to run the `build:schematics` script in the process of packaging/publishing the new module.
 
 ### Register your module as official module
 
@@ -68,4 +71,5 @@ To provide modules at Otter installation time, you just need to add the keyword
 }
 ```
 
-> **Note**: Only the modules published to [npmjs.org](https://www.npmjs.com/) will be detected.
+> [!NOTE]
+> Only the modules published to [npmjs.org](https://www.npmjs.com/) will be detected.

docs/dev-tools/chrome-devtools.md

@@ -23,7 +23,8 @@ The Otter module will automatically register its Devtool service if the followin
 }
 ```
 
-> **Note**: This options is set by the `--with-devtool` options of the `ng add @o3r/core` command.
+> [!NOTE]
+> This options is set by the `--with-devtool` options of the `ng add @o3r/core` command.
 
 ## How to enable manually the extension support in your application
 
@@ -83,7 +84,8 @@ export class AppComponent {
 }
 ```
 
-> **Note**: The services can be also activated at bootstrap time by providing `isActivatedOnBootstrap: true` to their dedicated token `OTTER_<module>_DEVTOOLS_OPTIONS` (example: `{provide: 'OTTER_CONFIGURATION_DEVTOOLS_OPTIONS', useValue: {isActivatedOnBootstrap: true}}`).
+> [!TIP]
+> The services can be also activated at bootstrap time by providing `isActivatedOnBootstrap: true` to their dedicated token `OTTER_<module>_DEVTOOLS_OPTIONS` (example: `{provide: 'OTTER_CONFIGURATION_DEVTOOLS_OPTIONS', useValue: {isActivatedOnBootstrap: true}}`).
 
 ## How to install the extension
 

docs/dev-tools/console-devtools.md

@@ -64,7 +64,8 @@ export class AppComponent {
 }
 ```
 
-> **Note**: The services can be also activated at bootstrap time by providing `isActivatedOnBootstrap: true` to their dedicated token `OTTER_<module>_DEVTOOLS_OPTIONS` (example: `{provide: 'OTTER_CONFIGURATION_DEVTOOLS_OPTIONS', useValue: {isActivatedOnBootstrap: true}}`).
+> [!TIP]
+> The services can be also activated at bootstrap time by providing `isActivatedOnBootstrap: true` to their dedicated token `OTTER_<module>_DEVTOOLS_OPTIONS` (example: `{provide: 'OTTER_CONFIGURATION_DEVTOOLS_OPTIONS', useValue: {isActivatedOnBootstrap: true}}`).
 
 ## How to use it