[DOC] adapt documentation to env changes

part of #430

doc/comparison.md

@@ -274,7 +274,7 @@ class Counter extends Component {
   dispatch = useDispatch();
 }
 
-owl.config.env.store = store;
+Counter.env.store = store;
 const counter = new Counter();
 ```
 

doc/learning/environment.md

@@ -40,7 +40,7 @@ async function myEnv() {
 }
 
 async function start() {
-  owl.config.env = await myEnv();
+  App.env = await myEnv();
   const app = new App();
   await app.mount(document.body);
 }

doc/learning/quick_start.md

@@ -97,8 +97,7 @@ class ClickCounter extends owl.Component {
 //------------------------------------------------------------------------------
 async function start() {
   const templates = await owl.utils.loadFile("templates.xml");
-  const qweb = new owl.QWeb({ templates });
+  ClickCounter.env = { qweb: new owl.QWeb({ templates }) };
-  owl.config.env.qweb = qweb;
   const counter = new ClickCounter();
   const target = document.getElementById("main");
   await counter.mount(target);

doc/readme.md

@@ -50,15 +50,14 @@ Store                                       Link
 useState                                    RouteComponent
 config                                      Router
     mode                                tags
-    env                                     xml
+core                                        xml
-core                                    utils
+    EventBus                            utils
-    EventBus                                debounce
+    Observer                                debounce
-    Observer                                escape
+hooks                                       escape
-hooks                                       loadJS
+    onWillStart                             loadJS
-    onWillStart                             loadFile
+    onMounted                               loadFile
-    onMounted                               shallowEqual
+    onWillUpdateProps                       shallowEqual
-    onWillUpdateProps                       whenReady
+    onWillPatch                             whenReady
-    onWillPatch
     onPatched
     onWillUnmount
     useContext

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),
+- [`mode`](#mode).
-- [`env`](#env).
 
 ## 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>
+    <div>
-          <t t-if=device.isMobile>
+      <t t-if=device.isMobile>
-             some simplified user interface
+          some simplified user interface
-          </t>
+      </t>
-          <t t-else="1">
+      <t t-else="1">
-             some more sopthisticated user interface
+          a more advanced user interface
-          </t>
+      </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
+An environment is an object which contains a [`QWeb` instance](qweb.md). Whenever
-is then automatically given to each sub component (and accessible in the `this.env` property).
+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)
+## Setting an environment
-- [Customizing an environment](config.md#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 `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
 ```
 

src/component/component.ts

@@ -136,7 +136,7 @@ export class Component<T extends Env, Props extends {}> {
       if (!this.env.qweb) {
         this.env.qweb = new QWeb();
       }
-      this.props = undefined as unknown as Props;
+      this.props = (undefined as unknown) as Props;
       this.env.qweb.on("update", this, () => {
         if (this.__owl__.isMounted) {
           this.render(true);

src/config.ts

@@ -19,7 +19,7 @@ Object.defineProperty(config, "mode", {
   set(mode: string) {
     QWeb.dev = mode === "dev";
     if (QWeb.dev) {
-      const url = `https://github.com/odoo/owl/blob/master/doc/tooling.md#development-mode`;
+      const url = `https://github.com/odoo/owl/blob/master/doc/reference/config.md#mode`;
       console.warn(
         `Owl is running in 'dev' mode.  This is not suitable for production use. See ${url} for more information.`
       );