From 7881bd5d3b5413acf08de242fbc3b005f96ff31b Mon Sep 17 00:00:00 2001 From: Nicolas Clavaud Date: Thu, 18 Feb 2021 12:46:40 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Petites=20corrections=20typograp?= =?UTF-8?q?hiques?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- publicodes/docs/api.md | 36 +++++++++++++++------------- publicodes/docs/communauté.md | 5 ++-- publicodes/docs/mecanisms.yaml | 26 ++++++++++---------- publicodes/docs/principes-de-base.md | 34 +++++++++++++------------- publicodes/docs/se-lancer.md | 16 ++++++------- 5 files changed, 61 insertions(+), 56 deletions(-) diff --git a/publicodes/docs/api.md b/publicodes/docs/api.md index c16631f93..b00efe1a6 100644 --- a/publicodes/docs/api.md +++ b/publicodes/docs/api.md @@ -1,6 +1,6 @@ # API -> **IMPORTANT** : publicodes est encore en version beta, et l'API peut-être sujette à des changements cassants lors de prochaines version. Pour plus d'informations, se référer à la [feuille de route v1.0](https://github.com/betagouv/mon-entreprise/issues/1293) +> **IMPORTANT** : publicodes est encore en version beta, et l'API peut-être sujette à des changements cassants lors de prochaines versions. Pour plus d'informations, se référer à la [feuille de route v1.0](https://github.com/betagouv/mon-entreprise/issues/1293) ## _new_ `Engine(rules)` @@ -8,34 +8,36 @@ Crée un moteur d'évaluation avec les règles publicodes données en argument. **Arguments** -- `rules` : les règles publicodes utilisée. Ces dernières peuvent-être sous la - forme d'une chaine de caractère `yaml` publicodes (ou d'un object javascript - correspondant). Elle peuvent aussi être sous la forme de règles publicodes déjà parsées +- `rules` : les règles publicodes utilisées. Ces dernières peuvent être sous la + forme d'une chaîne de caractère `yaml` publicodes (ou d'un objet javascript + correspondant). Elle peuvent aussi être sous la forme de règles publicodes déjà parsées. **Retourne** Un moteur d'évaluation qui expose les fonctions suivantes : -- setSituation -- evaluate -- getRule +- `setSituation` +- `evaluate` +- `getRule` ### _method_ `engine.setSituation(situation)` Permet de spécifier une situation en entrée. Toutes les prochaines évaluations seront effectuées en se basant sur ces valeurs plutôt que les valeurs présentes -dans la base de règle. +dans la base de règles. C'est le point d'entrée principal pour adapter les calculs de règles générales à une situation particulière. La situation est gardée en mémoire, et chaque appel à `setSituation` remplace la situation précédente. Le moteur -contient donc un _état interne_. Cela permet d'obtenir de meilleure performance, +contient donc un _état interne_. Cela permet d'obtenir de meilleures performances, avec une gestion plus fine du cache de calcul. En revanche, il faut prêter une grande attention à la bonne gestion de cet état interne. **Arguments** - `situation` : un objet javascript qui associe le nom complet d'une règle à sa - valeur. Cette valeur peut être n'importe quelle expression publicodes bien formée. Elle sera évaluée par le moteur. Cela permet de spécifier des nombre avec unité, des expressions, des références vers d'autres règles ou même d'utiliser des mécanismes. + valeur. Cette valeur peut être n'importe quelle expression publicodes bien formée. + Elle sera évaluée par le moteur. Cela permet de spécifier des nombres avec unité, + des expressions, des références vers d'autres règles ou même d'utiliser des mécanismes. **Retourne** @@ -51,9 +53,11 @@ dans un cache. Par conséquent, les appels suivants seront plus rapides. **Arguments** -- `expression`: la valeur à évaluer. Cela peut-être n'importe quelle expression publicodes bien formée (expression arithmétique, mécanisme, réference vers une règle) +- `expression`: la valeur à évaluer. Cela peut-être n'importe quelle expression publicodes + bien formée (expression arithmétique, mécanisme, réference vers une règle). **Retourne** + Un objet javascript de type `EvaluatedNode` contenant la valeur calculée. > **Attention !** Il est déconseillé d'utiliser directement les valeurs présentes @@ -87,9 +91,9 @@ Formate la valeur evaluée. La chaîne de caractère correspondant à la valeur bien formatée. -# Composants react +# Composants React -Publicodes exporte des composants react permettant d'afficher une documentation +Publicodes exporte des composants React permettant d'afficher une documentation explorable des calculs. Cette documentation est auto-générée en s'appuyant sur les données descriptives contenues dans les règles publicodes (description, références, titre, note, etc.) et en affichant pour chaque règle les étapes @@ -99,7 +103,7 @@ intermédiaires qui permettent d'aboutir au résultat affiché. ## `` -Composant react permettant d'afficher une documentation explorable d'une base de +Composant React permettant d'afficher une documentation explorable d'une base de règles publicodes. Se base sur react-router pour créer une arborescence de pages correspondant aux espaces de noms existants dans les règles. @@ -116,7 +120,7 @@ action (il est affiché sur l'écran de droite). ## `` -Composant react permettant de faire un lien vers une page de la documentation. +Composant React permettant de faire un lien vers une page de la documentation. Par défaut, le texte affiché est le nom de la règle. **Props** @@ -126,5 +130,5 @@ Par défaut, le texte affiché est le nom de la règle. montée. Doit correspondre à celui précisé pour le composant `` - `dottedName`: le nom de la règle à afficher - `displayIcon`: affiche l'icône de la règle dans le lien (par défaut à `false`) -- `children`: un noeud react quelconque. Par défaut, c'est le nom de la règle +- `children`: un noeud React quelconque. Par défaut, c'est le nom de la règle qui est utilisé. diff --git a/publicodes/docs/communauté.md b/publicodes/docs/communauté.md index 45b831915..2dafbe32f 100644 --- a/publicodes/docs/communauté.md +++ b/publicodes/docs/communauté.md @@ -2,12 +2,13 @@ - **[mon-entreprise.fr](https://mon-entreprise.fr/simulateurs)** utilise publicodes pour spécifier l'ensemble des calculs relatifs à la législation socio-fiscale - en France. Le site permet entre autre de simuler une fiche de paie complète, + en France. Le site permet entre autres de simuler une fiche de paie complète, de calculer les cotisations sociales pour un indépendant ou encore connaître le montant du chômage partiel. - **[futur.eco](https://futur.eco/)** utilise publicodes pour calculer les bilans carbone d'un grand nombre d'activités, plats, transports ou biens. -- **[Nos Gestes Climat](https://ecolab.ademe.fr/apps/climat)** utilise publicodes pour proposer un calculateur d'empreinte climat personnel de référence complètement ouvert +- **[Nos Gestes Climat](https://ecolab.ademe.fr/apps/climat)** utilise publicodes pour + proposer un calculateur d'empreinte climat personnel de référence complètement ouvert. ## ✍️ Contribuer diff --git a/publicodes/docs/mecanisms.yaml b/publicodes/docs/mecanisms.yaml index a8c926995..d1d44b725 100644 --- a/publicodes/docs/mecanisms.yaml +++ b/publicodes/docs/mecanisms.yaml @@ -33,7 +33,7 @@ une de ces conditions: Renvoie `oui` si l'une des règles listées est _applicable_. - Equivaut à un `ou` logique. + Équivaut à un `ou` logique. retourne: Booléen exemples: base: >- @@ -49,7 +49,7 @@ toutes ces conditions: Renvoie `oui` si toutes toutes les règles listées sont _applicables_. - Equivaut à un `et` logique. + Équivaut à un `et` logique. argument: - '*' - ... @@ -79,7 +79,7 @@ produit: assiette: Valeur à multiplier taux: Taux à appliquer facteur: Facteur multiplicatif - plafond: Plafond au dessus duquel le taux appliqué est nul + plafond: Plafond au-dessus duquel le taux appliqué est nul exemples: base: >- @@ -148,7 +148,7 @@ somme: Somme de chaque terme de la liste. - Si un des terme n'est pas applicable, il vaut zéro. + Si un des termes n'est pas applicable, il vaut zéro. On peut retrancher des valeurs grâce à l'opérateur unaire `-` @@ -207,7 +207,7 @@ le minimum de: arrondi: chainable: oui description: >- - Arrondi à l'entier le plus proche, ou à une précision donnée. + Arrondit à l'entier le plus proche, ou à une précision donnée. exemples: base: >- arrondi: @@ -348,16 +348,16 @@ composantes: Cela permet d'avoir une écriture factorisée, plus facile à lire. Dans les calculs, `composantes` se comporte **exactement comme une somme**. - La documentation, elle, sera adaptée pour montrer chaque composantes. + La documentation, elle, sera adaptée pour montrer chaque composante. Il est possible par exemple pour le mécanisme `produit` de garder en commun l'assiette, et de déclarer des composantes pour le taux. Chaque composante peut également contenir un champs `attributs` de type objet - contenant les mécanismes chainés à appliquer à la composante en question + contenant les mécanismes chainés à appliquer à la composante en question. - Lorsque l'on utilise l'attribut `nom`, cela abouti à la définition de règles - imbriquées pour chacun des terme de la somme. + Lorsque l'on utilise l'attribut `nom`, cela aboutit à la définition de règles + imbriquées pour chacun des termes de la somme. exemples: base: >- @@ -469,7 +469,7 @@ unité: par défaut: chainable: oui description: | - Permet de donner une valeur par défaut pour le calcul, sans influer sur les variables manquantes retournés. + Permet de donner une valeur par défaut pour le calcul, sans influer sur les variables manquantes retournées. Utile dans le cas d'une situation incomplète où l'on veut quand même retourner une première estimation. @@ -485,9 +485,9 @@ par défaut: synchronisation: description: >- - Permet de récupérer certaines informations, tels que les les + Permet de récupérer certaines informations, telles que les codes postaux des villes, à partir d'APIs externes, telles que l'[API - commune](https://geo.api.gouv.fr/decoupage-administratif/communes). + des communes de France](https://geo.api.gouv.fr/decoupage-administratif/communes). Attention, ce mécanisme est encore en cours de développement, et sa syntaxe @@ -515,7 +515,7 @@ inversion numérique: Brent](https://fr.wikipedia.org/wiki/M%C3%A9thode_de_Brent). L'idée générale est de prendre une valeur au hasard pour la variable en question, et d'améliorer mathématiquement le choix jusqu'à ce que les valeurs cibles - soient toutes suffisamment proches des objectifs + soient toutes suffisamment proches des objectifs. Si on demande au moteur la valeur d'une variable qui a pour formule une diff --git a/publicodes/docs/principes-de-base.md b/publicodes/docs/principes-de-base.md index e4a61f1ee..9a64a2e54 100644 --- a/publicodes/docs/principes-de-base.md +++ b/publicodes/docs/principes-de-base.md @@ -51,18 +51,18 @@ prix total: nombre de repas * prix d'un repas + frais de réservation # La formule de "prix total" est invalide. ``` -Dans l'exemple ci-dessus Publicode détecte une erreur car les termes de +Dans l'exemple ci-dessus, Publicode détecte une erreur car les termes de l'addition ont des unités incompatibles : d'un côté on a des `€` et de l'autre des `€/repas`. -Cette incohérence d'unité témoigne d'une erreur de logique. Ici une manière de corriger l'erreur peut être de factoriser la variable "nombre de repas" dans la formule du "prix total". +Cette incohérence d'unité témoigne d'une erreur de logique. Ici, une manière de corriger l'erreur peut être de factoriser la variable "nombre de repas" dans la formule du "prix total". ```yaml prix total: nombre de repas * (prix d'un repas + frais de réservation) ``` > **Attention :** Il ne faut pas insérer d'espace autour de la barre oblique dans -> les unités, l'unité `€ / mois` doit être notée `€/mois` +> les unités, l'unité `€ / mois` doit être notée `€/mois`. Publicode convertit automatiquement les unités si besoin. @@ -71,7 +71,7 @@ salaire: 1500 €/mois prime faible salaire applicable: salaire < 20 k€/an ``` -> NB : On peut forcer la conversion des unités via le [mécanisme `unité`](/mécanismes#unité) +> NB : On peut forcer la conversion des unités via le [mécanisme `unité`](/mécanismes#unité). **Types de base disponibles pour la conversion :** @@ -80,7 +80,7 @@ prime faible salaire applicable: salaire < 20 k€/an ## Mécanismes -Il existe une autre manière d'écrire des formules de calcul : les mécanismes. Au lieu de définir la formule sur une ligne, celle-ci prends la forme d'un objet sur plusieurs lignes. +Il existe une autre manière d'écrire des formules de calcul : les mécanismes. Au lieu de définir la formule sur une ligne, celle-ci prend la forme d'un objet sur plusieurs lignes. Par exemple, la formule suivante : @@ -88,7 +88,7 @@ Par exemple, la formule suivante : prix total: 5 repas * prix d'un repas ``` -Peut également s'écrire en utilisant le mécanisme [`produit`](/mécanismes/produit) : +peut également s'écrire en utilisant le mécanisme [`produit`](/mécanismes/produit) : ```yaml prix total: @@ -110,7 +110,7 @@ prix TTC: ### Mécanismes chaînés -Certains mécanismes peuvent apparaître au même niveau d'indentation. Dans ce cas, le moteur appliquera les transformations dans un ordre préetabli. +Certains mécanismes peuvent apparaître au même niveau d'indentation. Dans ce cas, le moteur appliquera les transformations dans un ordre préétabli. ```yaml remboursement repas: @@ -126,7 +126,7 @@ remboursement repas: L'explication des règles est un des objectifs fondamentaux de Publicodes. -Chaque règle se voit générer automatiquement une page explicatives +Chaque règle se voit générer automatiquement une page explicative correspondante dans le front-end, contenant une information facilement digeste mise en regard des calculs eux-mêmes. @@ -191,11 +191,11 @@ prime de vacances: valeur: 200€ ``` -Ici si l'ancienneté est inférieure à un an la prime de vacances ne sera pas -_applicable_. Les variables _non applicables_ sont égale à `non`. Elles sont ignorées au niveau des mécanismes numériques (par exemple le mécanisme `somme` comptera une prime non applicable +Ici, si l'ancienneté est inférieure à un an, alors la prime de vacances ne sera pas +_applicable_. Les variables _non applicables_ sont égales à `non`. Elles sont ignorées au niveau des mécanismes numériques (par exemple le mécanisme `somme` comptera une prime non applicable comme valant zéro, voir la page spécifique aux mécanismes). -La syntaxe suivante est également valable: +La syntaxe suivante est également valable : ```yaml assimilé salarié: @@ -216,14 +216,14 @@ prime de vacances . taux: formule: 6% ``` -Ici `prime de vacances` est à la fois une règle et un espace de noms. La variable +Ici, `prime de vacances` est à la fois une règle et un espace de noms. La variable `taux` est définie dans cet espace de noms et c'est elle qui est référencée dans la formule de calcul de la règle `prime de vacances`. La règle `prime de vacances` est elle-même définie dans l'espace de nom racine. On pourrait avoir une autre variable `taux` dans un espace de nom -différent, sans que cela entre en conflit: +différent, sans que cela entre en conflit : ```yaml # Ceci n'entre pas dans le calcul de `prime de vacances` définie plus haut @@ -278,8 +278,8 @@ indemnités: Certaines règles ne s'appliquent parfois que dans quelques situations particulières et modifier la définition des règles générales pour prendre en -compte ces particularités pose des problème de maintenabilité de la base de -règle. +compte ces particularités pose des problèmes de maintenabilité de la base de +règles. Publicode dispose d'un mécanisme de remplacement qui permet d'amender n'importe quelle règle existante sans avoir besoin de la modifier : @@ -295,7 +295,7 @@ convention hôtels cafés restaurants . frais de repas: montant repas mensuels: 20 repas * frais de repas ``` -On peut également choisir de remplacer dans un contexte donné: +On peut également choisir de remplacer dans un contexte donné : ```yaml temps de préparation: 20 min @@ -372,7 +372,7 @@ super-prime: Lors de l'évaluation, les variables dont les valeurs ne sont pas renseignées sont remontées afin que ces dernières puissent être complétées par l'utilisateur (dans le cas d'un simulateur par exemple). -Il est possible de donner une valeur par défaut. Les variables manquantes seront quand même remontée, et le moteur utilisera la valeur par défaut pour le calcul. +Il est possible de donner une valeur par défaut. Les variables manquantes seront quand même remontées, et le moteur utilisera la valeur par défaut pour le calcul. ```yaml durée: diff --git a/publicodes/docs/se-lancer.md b/publicodes/docs/se-lancer.md index 8087b59ac..95a5171e6 100644 --- a/publicodes/docs/se-lancer.md +++ b/publicodes/docs/se-lancer.md @@ -4,7 +4,7 @@ Publicode est distribué sous la forme d'une librairie [Node.js](https://nodejs.org/fr/) permettant de compiler un jeu de règles publicodes et de l'évaluer dans une situation donnée. -Le paquet est disponble sur NPM : +Le paquet est disponible sur npm : ```sh $ npm install publicodes @@ -66,7 +66,7 @@ const engine = new Engine(rules) > ``` La variable `engine` permet en ensuite de calculer la valeur d'une règle avec la -méthode `evaluate`. +méthode `evaluate` : ```js console.log(engine.evaluate('dépenses primeur')) @@ -74,7 +74,7 @@ console.log(engine.evaluate('dépenses primeur')) La valeur du nœud est disponible dans la propriété `nodeValue`, son unité est disponible dans la propriété `unit`. Mais pour un formattage sans -effort, on préfèrera utiliser la fonction `formatValue` +effort, on préfèrera utiliser la fonction `formatValue` : ```js import Engine, { formatValue } from 'publicodes' @@ -84,7 +84,7 @@ console.log(`J'ai dépensé ${formatValue(dépenses)} chez le primeur.`) ``` La méthode `setSituation` permet de forcer la valeur d'une liste de règles. Elle -est utile pour préciser les paramètres spécifiques à une simulation. +est utile pour préciser les paramètres spécifiques à une simulation : ```js // Ici on change le prix des avocats @@ -106,7 +106,7 @@ console.log( ### Évaluation d'expressions -La fonction `evaluate` permet d'évaluer des expressions publicode complètes +La fonction `evaluate` permet d'évaluer des expressions publicode complètes : ```js // On va au marché une fois par semaine, amortissons la dépense sur 7 jours @@ -132,9 +132,9 @@ console.log(`J'ai dépensé ${formatValue(depensesParMois)}.`) ### Variables manquantes -Publicode calcule automatiquement les dépendances de chaque règle. Si une la -valeur d'une dépendance est manquante et ne permet pas de faire le calcul elle -apparaîtra dans la propriété `missingVariables` +Publicode calcule automatiquement les dépendances de chaque règle. Si la +valeur d'une dépendance est manquante et ne permet pas de faire le calcul, elle +apparaîtra dans la propriété `missingVariables` : ```js const missingYEngine = new Engine(`