[DOC] update the documentation to new config and env

part of #306

doc/reference/component.md

@@ -11,7 +11,6 @@
   - [Methods](#methods)
   - [Lifecycle](#lifecycle)
   - [Root Component](#root-component)
-  - [Environment](#environment)
   - [Composition](#composition)
   - [Event Handling](#event-handling)
   - [Form Input Bindings](#form-input-bindings)
@@ -81,8 +80,8 @@ a state object is defined, by using the `useState` hook. It is not mandatory to
 ## Reference
 
 An Owl component is a small class which represents a component or some UI element.
-It exists in the context of an environment (`env`), which is propagated from a
-parent to its children. The environment needs to have a QWeb instance, which
+It exists in the context of an [environment](environment.md) (`env`), which is propagated from a
+parent to its children. The environment needs to have a [QWeb](qweb.md) instance, which
 will be used to render the component template.
 
 Be aware that the name of the component may be significant: if a component does
@@ -441,49 +440,12 @@ of an Owl application has to be created manually:
 ```js
 class App extends owl.Component { ... }
 
-const qweb = new owl.QWeb({ templates: TEMPLATES });
-const env = { qweb: qweb };
-const app = new App(env);
+const app = new App();
 app.mount(document.body);
 ```
 
-The root component needs an environment.
-
-### Environment
-
-In Owl, an environment is an object with a `qweb` key, which has to be a
-[QWeb](qweb.md) instance. This qweb instance will be used to render everything.
-
-The environment is meant to contain (mostly) static global information and
-methods for the whole application. For example, settings keys (`mode` to determine
-if we are in desktop or mobile mode, or `theme`: dark or light), `rpc` methods,
-session information, ...
-
-The environment will be given to each child, unchanged, in the `env` property.
-This can be very useful to share common information/methods. For example, all
-rpcs can be made through a `rpc` method in the environment. This makes it very
-easy to test a component.
-
-Updating the environment is not as simple as changing a component's state: its
-content is not observed, so updates will not be reflected immediately in the
-user interface. There is however a mechanism to force root widgets to rerender
-themselves whenever the environment is modified: one only needs to call the
-`forceUpdate` method on the QWeb instance. For example, a responsive environment
-could be done like this:
-
-```js
-function setupResponsivePlugin(env) {
-  const isMobile = () => window.innerWidth <= 768;
-  env.isMobile = isMobile();
-  const updateEnv = owl.utils.debounce(() => {
-    if (env.isMobile !== isMobile()) {
-      env.isMobile = !env.isMobile;
-      env.qweb.forceUpdate();
-    }
-  }, 15);
-  window.addEventListener("resize", updateEnv);
-}
-```
+The root component does not have a parent nor props. It will be setup with an
+[environment](environment.md) (located in `owl.config.env`).
 
 ### Composition
 
@@ -986,7 +948,7 @@ of the props. Here is how it works in Owl:
 - `props` key is a static key (so, different from `this.props` in a component instance)
 - it is optional: it is ok for a component to not define a `props` key.
 - props are validated whenever a component is created/updated
-- props are only validated in `dev` mode (see [tooling page](../tooling.md#development-mode))
+- props are only validated in `dev` mode (see [config page](config.md#mode))
 - if a key does not match the description, an error is thrown
 - it validates keys defined in (static) `props`. Additional keys given by the
   parent will cause an error.

doc/reference/config.md

@@ -0,0 +1,56 @@
+# 🦉 Config 🦉
+
+The Owl framework is designed to work in many situations.  However, it is
+sometimes necessary to customize some behaviour.  This is done by using the
+global `config` object. It currently has two keys:
+
+- [`mode`](#mode),
+- [`env`](#env).
+
+## Mode
+
+By default, Owl is in _production_ mode, this means that it will try to do its
+job fast, and skip some expensive operations. However, it is sometimes necessary
+to have better information on what is going on, this is the purpose
+of the `dev` mode.
+
+Owl has a mode flag, in `owl.config.mode`. Its default value is `prod`, but
+it can be set to `dev`:
+
+```js
+owl.config.mode = "dev";
+```
+
+Note that templates compiled with the `prod` settings will not be recompiled.
+So, changing this setting is best done at startup.
+
+An important job done by the `dev` mode is to validate props for each component
+creation and update. Also, extra props will cause an error.
+
+## Env
+
+An Owl application needs an [environment](environment.md) to be executed. The
+environment has an important key: the [QWeb](qweb.md) instance, which will render
+all templates.
+
+Whenever a root component is mounted, Owl will take the environment from
+`owl.config.env` and use it to setup the component (and its children).
+
+- if no environment was setup, an empty environment will be generated,
+- if an environment exists, but does not have a QWeb key, a new QWeb instance
+  will then be added to the environment.
+
+The correct way to customize an environment is to simply modify `owl.config.env`
+before the first component is created:
+
+```js
+owl.config.env = {
+    _t: myTranslateFunction,
+    user: {...},
+    services: {
+        ...
+    },
+};
+const app = new App();
+app.mount(document.body);
+```

doc/reference/context.md

@@ -28,10 +28,7 @@ context, and add it to the environment:
 
 ```js
 const deviceContext = new Context({ isMobile: true });
-const env = {
-  qweb: new QWeb({ templates: TEMPLATES }),
-  deviceContext
-};
+owl.config.env.deviceContext = deviceContext;
 ```
 
 If we want to make it completely responsive, we need to update its value whenever

doc/reference/environment.md

@@ -0,0 +1,18 @@
+# 🦉 Environment 🦉
+
+An environment is an object which contains a [`QWeb` instance](qweb.md). Whenever a root component is created, it is assigned an environment. This environment
+is then automatically given to each sub component (and accessible in the `this.env` property).
+
+```
+    Root
+    /  \
+   A    B
+```
+
+This way, all components share the same `QWeb` instance.
+
+Note: some additional information can be found here:
+
+- [What should go into an environment?](../learning/environment.md)
+- [Customizing an environment](config.md#env)
+

doc/reference/qweb.md

@@ -159,7 +159,7 @@ Its API is quite simple:
   ```
 
 In some way, a `QWeb` instance is the core of an Owl application. It is the only
-mandatory element of an [environment](component.md#environment). As such, it
+mandatory element of an [environment](environment.md). As such, it
 has an extra responsibility: it can act as an event bus for internal communication
 between Owl classes. This is the reason why `QWeb` actually extends [EventBus](event_bus.md).
 

doc/reference/router.md

@@ -67,6 +67,9 @@ function makeEnvironment() {
     await env.router.start();
     return env;
 }
+
+owl.config.env = makeEnvironment();
+// create root component here
 ```
 
 Notice that the router needs to be started. This is an asynchronous operation