[DOC] adapt documentation to env changes

part of #430

doc/reference/component.md

@@ -444,7 +444,8 @@ app.mount(document.body);
 ```
 
 The root component does not have a parent nor props. It will be setup with an
-[environment](environment.md) (located in `owl.config.env`).
+[environment](environment.md) (either the `env` defined on its class, or a
+default empty environment).
 
 ### Composition
 

doc/reference/config.md

@@ -2,10 +2,9 @@
 
 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:
+global `config` object. It currently has one key:
 
-- [`mode`](#mode),
-- [`env`](#env).
+- [`mode`](#mode).
 
 ## Mode
 
@@ -26,31 +25,3 @@ 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,7 +28,7 @@ context, and add it to the environment:
 
 ```js
 const deviceContext = new Context({ isMobile: true });
-owl.config.env.deviceContext = deviceContext;
+App.env.deviceContext = deviceContext;
 ```
 
 If we want to make it completely responsive, we need to update its value whenever
@@ -53,14 +53,14 @@ fact that we are in a mobile or desktop mode.
 ```js
 class SomeComponent extends Component {
   static template = xml`
-        <div>
-          <t t-if=device.isMobile>
-             some simplified user interface
-          </t>
-          <t t-else="1">
-             some more sopthisticated user interface
-          </t>
-    `;
+    <div>
+      <t t-if=device.isMobile>
+          some simplified user interface
+      </t>
+      <t t-else="1">
+          a more advanced user interface
+      </t>
+    </div>`;
   device = useContext(this.env.deviceContext);
 }
 ```

doc/reference/environment.md

@@ -1,7 +1,10 @@
 # 🦉 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).
+An environment is an object which contains a [`QWeb` instance](qweb.md). Whenever
+a root component is created, it is assigned an environment (see
+[below](#setting-an-environment) for more info on this). This environment is
+then automatically given to each sub component (and accessible in the `this.env`
+property).
 
 ```
     Root
@@ -11,7 +14,40 @@ is then automatically given to each sub component (and accessible in the `this.e
 
 This way, all components share the same `QWeb` instance.
 
-Note: some additional information can be found here:
+Note: some additional information about what should go into an environment
+can be found in the [learning section](../learning/environment.md).
 
-- [What should go into an environment?](../learning/environment.md)
-- [Customizing an environment](config.md#env)
+## Setting an environment
+
+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 `App` is mounted, Owl will setup a valid environment by
+following the next steps:
+
+- take the `env` object defined on `App.env` (if no `env` was explicitely setup,
+  this will be return the empty `env` object defined on `Component`)
+- if `env.qweb` is not set, then Owl will create a `QWeb` instance.
+
+The correct way to customize an environment is to simply set it up on the root
+component class, before the first component is created:
+
+```js
+App.env = {
+    _t: myTranslateFunction,
+    user: {...},
+    services: {
+        ...
+    },
+};
+const app = new App();
+app.mount(document.body);
+```
+
+It is also possible to simply share an environment between all root components,
+by simply doing this:
+
+```js
+Component.env = myEnv; // will be the default env for all components
+```

doc/reference/router.md

@@ -68,7 +68,7 @@ function makeEnvironment() {
     return env;
 }
 
-owl.config.env = makeEnvironment();
+App.env = makeEnvironment();
 // create root component here
 ```