From fec1b92f35173137a107a9c720ce4c7f0fb73eea Mon Sep 17 00:00:00 2001
From: Maxime Quandalle <maxime@quandalle.com>
Date: Sun, 10 May 2020 13:16:13 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=96=8A=20R=C3=A9daction=20doc=20API=20pub?=
 =?UTF-8?q?licode?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../source/sites/publi.codes/Api.tsx          |  19 +++
 .../source/sites/publi.codes/App.tsx          |   2 +
 .../source/sites/publi.codes/Header.tsx       |   8 +-
 publicodes/docs/api.md                        | 145 ++++++++++++++++++
 4 files changed, 172 insertions(+), 2 deletions(-)
 create mode 100644 mon-entreprise/source/sites/publi.codes/Api.tsx
 create mode 100644 publicodes/docs/api.md

diff --git a/mon-entreprise/source/sites/publi.codes/Api.tsx b/mon-entreprise/source/sites/publi.codes/Api.tsx
new file mode 100644
index 000000000..fc32aa60f
--- /dev/null
+++ b/mon-entreprise/source/sites/publi.codes/Api.tsx
@@ -0,0 +1,19 @@
+import React from 'react'
+import { ScrollToTop } from 'Components/utils/Scroll'
+import { Header } from './Header'
+import api from '../../../../publicodes/docs/api.md'
+import { MarkdownWithAnchorLinks } from 'Components/utils/markdown'
+
+// TODO Améliorer l'affichage des blocs de code JS et les rendre executables
+
+export default function Api() {
+	return (
+		<>
+			<div className="app-content ui__ container" css="margin: 2rem 0">
+				<ScrollToTop />
+				<Header />
+				<MarkdownWithAnchorLinks source={api} />
+			</div>
+		</>
+	)
+}
diff --git a/mon-entreprise/source/sites/publi.codes/App.tsx b/mon-entreprise/source/sites/publi.codes/App.tsx
index 0375900a8..3dfc6f0c5 100644
--- a/mon-entreprise/source/sites/publi.codes/App.tsx
+++ b/mon-entreprise/source/sites/publi.codes/App.tsx
@@ -6,6 +6,7 @@ import { hot } from 'react-hot-loader'
 import { Route, Switch } from 'react-router-dom'
 import Provider from '../../Provider'
 import redirects from '../mon-entreprise.fr/redirects'
+import Api from './Api'
 import Landing from './Landing'
 import Studio from './LazyStudio'
 import Mécanismes from './Mécanismes'
@@ -25,6 +26,7 @@ const RouterSwitch = () => {
 				<Route exact path="/" component={Landing} />
 				<Route exact path="/studio" component={Studio} />
 				<Route exact path="/mécanismes" component={Mécanismes} />
+				<Route exact path="/api" component={Api} />
 				<Route component={App} />
 			</Switch>
 		</>
diff --git a/mon-entreprise/source/sites/publi.codes/Header.tsx b/mon-entreprise/source/sites/publi.codes/Header.tsx
index 08a5d5905..5d87b954e 100644
--- a/mon-entreprise/source/sites/publi.codes/Header.tsx
+++ b/mon-entreprise/source/sites/publi.codes/Header.tsx
@@ -30,11 +30,15 @@ export const Header = ({ noSubtitle = false, sectionName = '' }) => (
 		<nav css="display">
 			<NavLink activeStyle={activeStyle} to="/studio">
 				Bac à sable
-			</NavLink>{' '}
-			•{' '}
+			</NavLink>
+			{' • '}
 			<NavLink activeStyle={activeStyle} to="/mécanismes">
 				Liste des mécanismes
 			</NavLink>
+			{' • '}
+			<NavLink activeStyle={activeStyle} to="/api">
+				API
+			</NavLink>
 		</nav>
 	</header>
 )
diff --git a/publicodes/docs/api.md b/publicodes/docs/api.md
new file mode 100644
index 000000000..0f0a98d61
--- /dev/null
+++ b/publicodes/docs/api.md
@@ -0,0 +1,145 @@
+# Api ![béta](https://img.shields.io/badge/-beta-blue)
+
+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.
+
+## Installation
+
+Le paquet est disponble sur NPM :
+
+```sh
+$ npm install publicodes
+```
+
+Il est aussi possible d'utiliser la librairie directement dans le navigateur :
+
+```html
+<script src="https://publi.codes/publicode.js"></script>
+```
+
+## Utilisation
+
+### Introduction
+
+La libraire exporte un objet `Engine` qui permet d'instancier le moteur avec un
+jeu de règles publicodes :
+
+```js
+import Engine from 'publicodes'
+
+// On définit une liste de règles publicodes
+const rules = `
+prix . carottes: 2€/kg
+prix . champignons: 5€/kg
+prix . avocat: 2€/avocat
+
+dépenses primeur:
+  formule: 
+    somme:
+      - prix . carottes * 1.5 kg
+      - prix . champignons * 500g
+      - prix . avocat * 3 avocat
+`
+
+// On initialise un moteur en lui donnant le publicode.
+// Ce publicode va être parsé
+const engine = new Engine(rules)
+```
+
+La variable `engine` permet en ensuite de calculer la valeur d'une règle avec la
+méthode `evaluate`.
+
+```js
+console.log(engine.evaluate('dépenses primeur'))
+```
+
+La valeur numérique du nœud est disponible dans l'attribut `nodeValue`, son
+unité est disponible dans l'attribut `unit` :
+
+```js
+const { nodeValue, unit } = engine.evaluate('dépenses primeur')
+console.log(`j'ai dépensé ${nodeValue} ${unit} chez le primeur`)
+```
+
+La méthode `setSituation` permet de forcer la valeur d'une liste de règle. Elle
+utile pour pour présier les paramètres spécifiques à une simulation.
+
+```js
+// Ici on change le prix des avocats
+engine.setSituation({
+	'prix . avocat': '3€/avocat'
+})
+```
+
+La valeur de `dépenses primeur` se base maintenant sur un avocat à 3€ :
+
+```js
+// On ré-évalue la règle dans la nouvelle situation
+console.log(`Nouveau prix ! ${engine.evaluate('dépenses primeur').nodeValue}`)
+```
+
+### Évaluation d'expressions
+
+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
+engine.evaluate('dépenses primeur / 7 jours')
+```
+
+### Conversion d'unité
+
+Publicode permet de réaliser des conversions d'unités. Pour celà il faut
+indiquer l'unité désirée comme paramètre à la méthode `evaluate` :
+
+```js
+// on va au march" une fois par semaine, combien dépense-t-on par mois ?
+engine.evaluate('dépenses primeurs / 7 jours', { unit: '€/mois' })
+```
+
+[➡ en savoir plus sur les unités](https://publi.codes/#unités)
+
+### 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 l'attribut `missingVariables`
+
+```js
+const engine = new Engine(`
+x: y + 5
+
+y:
+`)
+
+console.log(engine.evaluate('x').missingVariables)
+```
+
+Cette information est utile pour intégrer publicode à votre application.
+
+Il est aussi possible d'utiliser des valeurs par défaut. Dans ce cas la règle
+sera calculée avec la valeur par défaut de sa dépendance, mais cette dernière
+apparaîtra tout de même dans les `missingVariables`. Cette fonctionnalité est
+utile pour réaliser des simulateurs où l'on veut proposer un résultat sans
+attendre que l'utilisateur n'ait répondu à l'intégralité des questions tout en
+utilisant la liste des variables manquantes pour déterminer les questions
+restant à poser.
+
+<!-- TODO : Exemple -->
+
+Les variables manquantes sont calculées lors de l'évaluation. Si une variable
+apparaît dans la formule de calcul d'une règle elle ne sera rapportée que si
+elle est effectivement nécessaire au calcul. Si elle est présente dans une
+portion non active de l'évaluation (par exemple dans un bloc condition non
+actif, ou la tranche d'un barème non actif) elle sera filtrée et n'apparaîtra
+pas dans les `missingVariables`
+
+<!-- TODO : Exemple -->
+
+## Référence
+
+- Engine constructor
+- engine.evaluate
+- engine.setSituation
+- formatValue