doc: improve the documentation, add a lot of information

README.md

@@ -1,48 +1,34 @@
 # 🦉 Odoo Web Lab 🦉
 
-## Overview
+## Project Overview
 
 Odoo Web Lab (OWL) is a project to collect some useful, reusable, (hopefully)
-well designed building blocks for building web applications.
+well designed building blocks for building web applications. However, since this is the basis for the Odoo web client, we will not hesitate
-
-However, since this is the basis for the Odoo web client, we will not hesitate
 to design the code here to better match the Odoo architecture/design principles.
 
-This project is also a playground to experiment with some ideas related to web
+The most important element of this repository is certainly the component system.
-technologies.
+It is designed to be:
 
-Currently, this repository contains:
+1. **declarative:** the user interface should be described in term of the state
+   of the application, not as a sequence of imperative steps.
 
-1. **core**
+2. **composable:** each widget can seamlessly be created in a parent widget by
+   a simple directive in its template.
 
-   - an implementation/extension of the QWeb template engine that outputs a virtual
+3. **asynchronous rendering:** the framework will transparently wait for each
-     dom (using the snabbdom library)
+   subwidgets to be ready before applying the rendering. It uses native promises
-   - a Component class, which uses the QWeb engine as its underlying rendering
+   under the hood.
-     mechanism. The component class is designed to be declarative, with
-     asynchronous rendering.
-   - some utility functions/classes
 
-2. **extras**
+4. **uses QWeb as a template system:** the templates are described in XML
-   - a Store class and a connect function, to help manage the state of an application (like react-redux)
+   and follow the QWeb specification. This is a requirement for Odoo.
-   - a Registry: this is a simple key/store mapping
 
-In the future, this repository may includes other features. Here are some
+5. **with an imperative escape hatch:** if necessary, sub widgets can easily be
-ideas:
+   manually created/destroyed.
-
-- a (frontend) router could be included.
-- basic infrastructure code for web views (form/list/kanban)
-- a mechanism to aggregate/query/dispatch rpcs (a little bit like graphql)
 
 Note: the code is written in typescript. This does not mean that the main web
 client will ever be converted to typescript (even though I would really like it).
 
----
+## Installing/Building
-
-**Warning!**
-
-This is currently a proof of concept, not yet production-ready.
-
-## Main scripts
 
 To install every dependency needed to play with this code:
 
@@ -67,7 +53,10 @@ Note that the test scripts also run the example tests suites.
 
 ## Documentation
 
+The complete documentation can be found [here](doc/readme.md). The most important sections are:
+
 - [Quick Start](doc/quick_start.md)
+- [Tutorial](doc/tutorial.md)
 - [Component](doc/component.md)
 - [QWeb](doc/qweb.md)
 
@@ -135,3 +124,7 @@ More interesting examples on how to work with this web framework can be found in
 - [Todo Application](examples/readme.md#todo-app)
 - [Web Client](examples/readme.md#web-client-example)
 - [Benchmarks](examples/readme.md#benchmarks)
+
+## License
+
+React is [GPL licensed](./LICENSE).

doc/readme.md

@@ -1,6 +1,22 @@
 # Odoo Web Lab Documentation
 
+Currently, this repository contains:
+
+1. **core**
+
+   - an implementation/extension of the QWeb template engine that outputs a virtual
+     dom (using the snabbdom library)
+   - a Component class, which uses the QWeb engine as its underlying rendering
+     mechanism. The component class is designed to be declarative, with
+     asynchronous rendering. Also, it uses snabbdom as the virtual dom library.
+   - some utility functions/classes
+
+2. **extras**
+   - a Store class and a connect function, to help manage the state of an application (like react-redux)
+   - a Registry: this is a simple key/store mapping
+
 - [Quick Start](quick_start.md)
+- [Tutorial](tutorial.md)
 - [Component](component.md)
 - [QWeb](qweb.md)
 - [State Management](state_management.md)

doc/tutorial.md

@@ -0,0 +1,3 @@
+# Tutorial
+
+todo...