[ADD] doc: new documentation, with training tutorials, and new scaffolding

10 files changed, 1231 insertions, 0 deletions

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
new file mode 100644
index 00000000000..dcedbe03eba
--- /dev/null
+++ b/doc/reference/cmdline.rst
@@ -0,0 +1,85 @@
+.. _reference/cmdline:
+
+===============================
+Command-line interface: oodo.py
+===============================
+
+.. _reference/cmdline/server:
+
+Running the server
+==================
+
+.. program:: odoo.py
+
+.. option:: -d <database>, --database=<database>
+
+    database used when installing or updating modules.
+
+.. option:: -i <modules>, --init=<modules>
+
+    comma-separated list of modules to :ref:`install
+    <reference/module/lifecycle/install>` before running the server.
+
+.. option:: -u <modules>, --update=<modules>
+
+    comma-separated list of modules to :ref:`update
+    <reference/module/lifecycle/update>` before running the server.
+
+.. option:: --addons-path <directories>
+
+    comma-separated list of directories in which modules are stored. These
+    directories are scanned for modules (nb: when and why?)
+
+.. option:: -c <config>, --config <config>
+
+    provide an alternate configuration file
+
+.. option:: -s, --save
+
+    saves the server configuration to the current configuration file
+    (:file:`{$HOME}/.openerp_serverrc` by default, overridable using
+    :option:`-c`)
+
+.. _reference/cmdline/scaffold:
+
+Scaffolding
+===========
+
+.. program:: odoo.py scaffold
+
+Scaffolding is the automated creation of a skeleton structure to simplify
+bootstrapping (of new modules, in the case of Odoo). While not necessary it
+avoids the tedium of setting up basic structures and looking up what all
+starting requirements are.
+
+Scaffolding is available via the :command:`odoo.py scaffold` subcommand.
+
+.. option:: -t <template>
+
+    a template directory, files are passed through jinja2_ then copied to
+    the :option:`destination` directory
+
+.. option:: name
+
+    the name of the module to create, may munged in various manners to
+    generate programmatic names (e.g. module directory name, model names, …)
+
+.. option:: destination
+
+    directory in which to create the new module, defaults to the current
+    directory
+
+.. _reference/cmdline/config:
+
+Configuration file
+==================
+
+Most of the command-line options can also be specified via a configuration
+file.
+
+The default configuration file is :file:`{$HOME}/.openerp_serverrc` which
+can be overridden using :option:`--config <odoo.py -c>`. Specifying
+:option:`--save <odoo.py -s>` will save the current configuration state back
+to that file.
+
+.. _jinja2: http://jinja.pocoo.org
diff --git a/doc/reference/data.rst b/doc/reference/data.rst
new file mode 100644
index 00000000000..6e9a004f9ac
--- /dev/null
+++ b/doc/reference/data.rst
@@ -0,0 +1,275 @@
+.. _reference/data:
+
+==========
+Data Files
+==========
+
+Odoo is greatly data-driven, and a big part of modules definition is thus
+the definition of the various records it manages: UI (menus and views),
+security (access rights and access rules), reports and plain data are all
+defined via records.
+
+Structure
+=========
+
+The main way to define data in Odoo is via XML data files: The broad structure
+of an XML data file is the following:
+
+* The nested root elements ``openerp`` and ``data``
+* Any number of operation elements within ``data``
+
+.. code-block:: xml
+
+    <!-- the root elements of the data file -->
+    <openerp><data>
+      <operation/>
+      ...
+    </data></openerp>
+
+Data files are executed sequentially, operations can only refer to the result
+of operations defined previously
+
+Core operations
+===============
+
+.. _reference/data/record:
+
+``record``
+----------
+
+``record`` appropriately defines or updates a database record, it has the
+following attributes:
+
+``model`` (required)
+    name of the model to create (or update)
+``id``
+    the :term:`external identifier` for this record. It is strongly
+    recommended to provide one
+
+    * for record creation, allows subsequent definitions to either modify or
+      refer to this record
+    * for record modification, the record to modify
+``context``
+    context to use when creating the record
+``forcecreate``
+    in :ref:`update mode <reference/module/lifecycle/update>`, whether the
+    record should be created if it doesn't exist.
+
+    Requires an :term:`external id`, defaults to ``True``.
+
+``field``
+'''''''''
+
+Each record can be composed of ``field`` tags, defining values to set when
+creating the record. A ``record`` with no ``field`` will use all default
+values (creation) or do nothing (update).
+
+A ``field`` has a mandatory ``name`` attribute, the name of the field to set,
+and various methods to define the value itself:
+
+Nothing
+    if no value is provided for the field, an implicit ``False`` will be set
+    on the field. Can be used to clear a field, or avoid using a default value
+    for the field.
+``search``
+    for :ref:`relational fields <reference/orm/fields/relational>`, should be
+    a :ref:`domain <reference/orm/domains>` on the field's model.
+
+    Will evaluate the domain, search the field's model using it and set the
+    search's result as the field's value. Will only use the first result if
+    the field is a :class:`~openerp.fields.Many2one`
+``ref``
+    if a ``ref`` attribute is provided, its value must be a valid
+    :term:`external id`, which will be looked up and set as the field's value.
+
+    Mostly for :class:`~openerp.fields.Many2one` and
+    :class:`~openerp.fields.Reference` fields
+``type``
+    if a ``type`` attribute is provided, it is used to interpret and convert
+    the field's content. The field's content can be provided through an
+    external file using the ``file`` attribute, or through the node's body.
+
+    Available types are:
+
+    ``xml``, ``html``
+        extracts the ``field``'s children as a single document, evaluates
+        any :term:`external id` specified with the form ``%(external_id)s``.
+        ``%%`` can be used to output actual *%* signs.
+    ``file``
+        ensures that the field content is a valid file path in the current
+        model, saves the pair :samp:`{module},{path}` as the field value
+    ``char``
+        sets the field content directly as the field's value without
+        alterations
+    ``base64``
+        base64_-encodes the field's content, useful combined with the ``file``
+        *attribute* to load e.g. image data into attachments
+    ``int``
+        converts the field's content to an integer and sets it as the field's
+        value
+    ``float``
+        converts the field's content to a float and sets it as the field's
+        value
+    ``list``, ``tuple``
+        should contain any number of ``value`` elements with the same
+        properties as ``field``, each element resolves to an item of a
+        generated tuple or list, and the generated collection is set as the
+        field's value
+``eval``
+    for cases where the previous methods are unsuitable, the ``eval``
+    attributes simply evaluates whatever Python expression it is provided and
+    sets the result as the field's value.
+
+    The evaluation context contains various modules (``time``, ``datetime``,
+    ``timedelta``, ``relativedelta``), a function to resolve :term:`external
+    identifiers` (``ref``) and the model object for the current field if
+    applicable (``obj``)
+
+``delete``
+----------
+
+The ``delete`` tag can remove any number of records previously defined. It
+has the following attributes:
+
+``model`` (required)
+    the model in which a specified record should be deleted
+``id``
+    the :term:`external id` of a record to remove
+``search``
+    a :ref:`domain <reference/orm/domains>` to find records of the model to
+    remove
+
+``id`` and ``search`` are exclusive
+
+``function``
+------------
+
+The ``function`` tag calls a method on a model, with provided parameters.
+It has two mandatory parameters ``model`` and ``name`` specifying respectively
+the model and the name of the method to call.
+
+Parameters can be provided using ``eval`` (should evaluate to a sequence of
+parameters to call the method with) or ``value`` elements (see ``list``
+values).
+
+``workflow``
+------------
+
+The ``workflow`` tag sends a signal to an existing workflow. The workflow
+can be specified via a ``ref`` attribute (the :term:`external id` of
+an existing workflow) or a ``value`` tag returning the id of a workflow.
+
+The tag also has two mandatory attributes ``model`` (the model linked to the
+workflow) and ``action`` (the name of the signal to send to the workflow).
+
+.. ignored assert
+
+Shortcuts
+=========
+
+Because some important structural models of Odoo are complex and involved,
+data files provide shorter alternatives to defining them using
+:ref:`record tags <reference/data/record>`:
+
+``menuitem``
+------------
+
+Defines an ``ir.ui.menu`` record with a number of defaults and fallbacks:
+
+Parent menu
+    * If a ``parent`` attribute is set, it should be the :term:`external id`
+      of an other menu item, used as the new item's parent
+    * If no ``parent`` is provided, tries to interpret the ``name`` attribute
+      as a ``/``-separated sequence of menu names and find a place in the menu
+      hierarchy. In that interpretation, intermediate menus are automatically
+      created
+    * Otherwise the menu is defined as a "top-level" menu item (*not* a menu
+      with no parent)
+Menu name
+    If no ``name`` attribute is specified, tries to get the menu name from
+    a linked action if any. Otherwise uses the record's ``id``
+Groups
+    A ``groups`` attribute is interpreted as a comma-separated sequence of
+    :term:`external identifiers` for ``res.groups`` models. If an
+    :term:`external identifier` is prefixed with a minus (``-``), the group
+    is *removed* from the menu's groups
+``action``
+    if specified, the ``action`` attribute should be the :term:`external id`
+    of an action to execute when the menu is open
+``id``
+    the menu item's :term:`external id`
+
+``template``
+------------
+
+Creates a :ref:`QWeb view <reference/views/qweb>` requiring only the ``arch``
+section of the view, and allowing a few *optional* attributes:
+
+``id``
+    the view's :term:`external identifier`
+``name``, ``inherit_id``, ``priority``
+    same as the corresponding field on ``ir.ui.view`` (nb: ``inherit_id``
+    should be an :term:`external identifier`)
+``primary``
+    if set to ``True`` and combined with a ``inherit_id``, defines the view
+    as a primary
+``groups``
+    comma-separated list of group :term:`external identifiers`
+``page``
+    if set to ``"True"``, the template is a website page (linkable to,
+    deletable)
+``optional``
+    ``enabled`` or ``disabled``, whether the view can be disabled (in the
+    website interface) and its default status. If unset, the view is always
+    enabled.
+
+``report``
+----------
+
+Creates a ``ir.actions.report.xml`` record with a few default values.
+
+Mostly just proxies attributes to the corresponding fields on
+``ir.actions.report.xml``, but also automatically creates the item in the
+:guilabel:`More` menu of the report's ``model``.
+
+.. ignored url, act_window and ir_set
+
+CSV data files
+==============
+
+XML data files are flexible and self-descriptive, but very verbose when
+creating a number of simple records of the same model in bulk.
+
+For this case, data files can also use csv_, this is often the case for
+:ref:`access rights <reference/security/acl>`:
+
+* the file name is :file:`{model_name}.csv`
+* the first row lists the fields to write, with the special field ``id``
+  for :term:`external identifiers` (used for creation or update)
+* each row thereafter creates a new record
+
+Here's the first lines of the data file defining US states
+``res.country.state.csv``
+
+.. literalinclude:: ../../openerp/addons/base/res/res.country.state.csv
+    :language: text
+    :lines: 1-15
+
+rendered in a more readable format:
+
+.. csv-table::
+    :file: ../../openerp/addons/base/res/res.country.state.csv
+    :header-rows: 1
+    :class: table-striped table-hover table-condensed
+
+For each row (record):
+
+* the first column is the :term:`external id` of the record to create or
+  update
+* the second column is the :term:`external id` of the country object to link
+  to (country objects must have been defined beforehand)
+* the third column is the ``name`` field for ``res.country.state``
+* the fourth column is the ``code`` field for ``res.country.state``
+
+.. _base64: http://tools.ietf.org/html/rfc3548.html#section-3
+.. _csv: http://en.wikipedia.org/wiki/Comma-separated_values
diff --git a/doc/reference/http.rst b/doc/reference/http.rst
new file mode 100644
index 00000000000..6459e2bbd1b
--- /dev/null
+++ b/doc/reference/http.rst
@@ -0,0 +1,27 @@
+===============
+Web Controllers
+===============
+
+Routing
+=======
+
+.. autofunction:: openerp.http.route
+
+.. _reference/http/request:
+
+Request
+=======
+
+Response
+========
+
+JSON-RPC
+========
+
+.. _reference/http/controllers:
+
+Extension: controllers
+======================
+
+.. this should be about inheritance/extension, do web controllers still do
+   anything else nowadays?
diff --git a/doc/reference/javascript.rst b/doc/reference/javascript.rst
new file mode 100644
index 00000000000..668543a906d
--- /dev/null
+++ b/doc/reference/javascript.rst
@@ -0,0 +1,9 @@
+==========
+Javascript
+==========
+
+Widgets
+=======
+
+RPC
+===
diff --git a/doc/reference/module.rst b/doc/reference/module.rst
new file mode 100644
index 00000000000..933b263f7ba
--- /dev/null
+++ b/doc/reference/module.rst
@@ -0,0 +1,80 @@
+=======
+Modules
+=======
+
+.. _reference/module/manifest:
+
+Manifest
+========
+
+The manifest file serves to both declare a python package as an Odoo module,
+and to specify a number of module metadata.
+
+It is a file called ``__openerp__.py`` and contains a single Python
+dictionary, each dictionary key specifying a module metadatum.
+
+Available manifest fields are:
+
+``name`` (``str``, required)
+    the human-readable name of the module
+``version`` (``str``)
+    this module's version, should follow `semantic versioning`_ rules
+``description`` (``str``)
+    extended description for the module, in reStructuredText
+``author`` (``str``)
+    name of the module author
+``website`` (``str``)
+    website URL for the module author
+``license`` (``str``, defaults: ``AGPL-3``)
+    distribution license for the module
+``category`` (``str``, default: ``Uncategorized``)
+    classification category within Odoo, rough business domain for the module.
+
+    Although using `existing categories`_ is recommended, the field is
+    freeform and unknown categories are created on-the-fly. Category
+    hierarchies can be created using the separator ``/`` e.g. ``Foo / Bar``
+    will create a category ``Foo``, a category ``Bar`` as child category of
+    ``Foo``, and will set ``Bar`` as the module's category.
+``depends`` (``list(str)``)
+    Odoo modules which must be loaded before this one, either because this
+    module uses features they create or because it alters resources they
+    define.
+
+    When a module is installed, all of its dependencies are installed before
+    it. Likewise during modules loading.
+``data`` (``list(str)``)
+    List of data files which must always be installed or updated with the
+    module. A list of paths from the module root directory
+``demo`` (``list(str)``)
+    List of data files which are only installed or updated in *demonstration
+    mode*
+``auto_install`` (``bool``, default: ``False``)
+    If ``True``, this module will automatically be installed if all of its
+    dependencies are installed.
+
+    It is generally used for "link modules" implementing synergic integration
+    between two otherwise independent modules.
+
+    For instance ``sale_crm`` depends on both ``sale`` and ``crm`` and is set
+    to ``auto_install``. When both ``sale`` and ``crm`` are installed, it
+    automatically adds CRM campaigns tracking to sale orders without either
+    ``sale`` or ``crm`` being aware of one another
+
+.. _reference/module/lifecycle:
+
+Lifecycle
+=========
+
+.. _reference/module/lifecycle/install:
+
+Install
+-------
+
+.. _reference/module/lifecycle/update:
+
+Update
+------
+
+.. _semantic versioning: http://semver.org
+.. _existing categories:
+     https://github.com/odoo/odoo/blob/master/openerp/addons/base/module/module_data.xml
diff --git a/doc/reference/orm.rst b/doc/reference/orm.rst
new file mode 100644
index 00000000000..3a1e1e6fd2a
--- /dev/null
+++ b/doc/reference/orm.rst
@@ -0,0 +1,353 @@
+.. _reference/orm:
+
+===
+ORM
+===
+
+.. _reference/orm/model:
+
+Model
+=====
+
+.. - can't get autoattribute to import docstrings, so use regular attribute
+   - no autoclassmethod
+
+.. currentmodule:: openerp.models
+
+.. autoclass:: openerp.models.Model
+
+    .. rubric:: Structural attributes
+
+    .. attribute:: _name
+
+        business object name, in dot-notation (in module namespace)
+
+    .. attribute:: _rec_name
+
+        Alternative field to use as name, used by osv’s name_get()
+        (default: ``'name'``)
+
+    .. attribute:: _inherit
+
+        * If :attr:`._name` is set, names of parent models to inherit from.
+          Can be a ``str`` if inheriting from a single parent
+        * If :attr:`._name` is unset, name of a single model to extend
+          in-place
+
+    .. attribute:: _order
+
+        Ordering field when searching without an ordering specified (default:
+        ``'id'``)
+
+        :type: str
+
+    .. attribute:: _auto
+
+        Whether a database table should be created (default: ``True``)
+
+        If set to ``False``, override :meth:`.init` to create the database
+        table
+
+    .. attribute:: _table
+
+        Name of the table backing the model created when
+        :attr:`~openerp.models.Model._auto`, automatically generated by
+        default.
+
+    .. attribute:: _inherits
+
+        dictionary mapping the _name of the parent business objects to the
+        names of the corresponding foreign key fields to use::
+
+            _inherits = {
+                'a.model': 'a_field_id',
+                'b.model': 'b_field_id'
+            }
+
+        implements composition-based inheritance: the new model exposes all
+        the fields of the :attr:`~openerp.models.Model._inherits`-ed model but
+        stores none of them: the values themselves remain stored on the linked
+        record.
+
+        .. warning::
+
+            if the same field is defined on multiple
+            :attr:`~openerp.models.Model._inherits`-ed
+
+    .. attribute:: _constraints
+
+        list of ``(constraint_function, message, fields)`` defining Python
+        constraints. The fields list is indicative
+
+        .. deprecated:: 8.0
+
+            use :func:`~openerp.api.constrains`
+
+    .. attribute:: _sql_constraints
+
+        list of ``(name, sql_definition, message)`` triples defining SQL
+        constraints to execute when generating the backing table
+
+    .. attribute:: _parent_store
+
+        Alongside :attr:`~.parent_left` and :attr:`~.parent_right`, sets up a
+        `nested set <http://en.wikipedia.org/wiki/Nested_set_model>`_  to
+        enable fast hierarchical queries on the records of the current model
+        (default: ``False``)
+
+        :type: bool
+
+    .. rubric:: CRUD
+
+    .. automethod:: create
+    .. automethod:: browse
+    .. automethod:: unlink
+    .. automethod:: write
+
+    .. automethod:: read
+
+    .. rubric:: Research
+
+    .. automethod:: search
+    .. automethod:: search_count
+    .. automethod:: name_search
+
+    .. rubric:: Recordset operations
+
+    .. autoattribute:: ids
+    .. automethod:: ensure_one
+    .. automethod:: exists
+    .. automethod:: filtered
+    .. automethod:: sorted
+    .. automethod:: update
+
+    .. rubric:: Environment swapping
+
+    .. automethod:: sudo
+    .. automethod:: with_context
+    .. automethod:: with_env
+
+    .. rubric:: Fields and views querying
+
+    .. automethod:: fields_get
+    .. automethod:: fields_view_get
+
+    .. rubric:: ???
+
+    .. automethod:: default_get
+    .. automethod:: copy
+    .. automethod:: add_default_value
+    .. automethod:: name_get
+    .. automethod:: name_create
+
+    .. rubric:: Automatic fields
+
+    .. attribute:: id
+
+        Identifier :class:`field <openerp.fields.Field>`
+
+    .. attribute:: _log_access
+
+        Whether log access fields (``create_date``, ``write_uid``, ...) should
+        be generated (default: ``True``)
+
+    .. attribute:: create_date
+
+        Date at which the record was created
+
+        :type: :class:`~openerp.field.Datetime`
+
+    .. attribute:: create_uid
+
+        Relational field to the user who created the record
+
+        :type: ``res.users``
+
+    .. attribute:: write_date
+
+        Date at which the record was last modified
+
+        :type: :class:`~openerp.field.Datetime`
+
+    .. attribute:: write_uid
+
+        Relational field to the last user who modified the record
+
+        :type: ``res.users``
+
+    .. rubric:: Reserved field names
+
+    A few field names are reserved for pre-defined behaviors beyond that of
+    automated fields. They should be defined on a model when the related
+    behavior is desired:
+
+    .. attribute:: name
+
+        default value for :attr:`~._rec_name`, used to
+        display records in context where a representative "naming" is
+        necessary.
+
+        :type: :class:`~openerp.fields.Char`
+
+    .. attribute:: active
+
+        toggles the global visibility of the record, if ``active`` is set to
+        ``False`` the record is invisible in most searches and listing
+
+        :type: :class:`~openerp.fields.Boolean`
+
+    .. attribute:: sequence
+
+        Alterable ordering criteria, allows drag-and-drop reordering of models
+        in list views
+
+        :type: :class:`~openerp.fields.Integer`
+
+    .. attribute:: state
+
+        lifecycle stages of the object, used by the ``states`` attribute on
+        :class:`fields <openerp.fields.Field>`
+
+        :type: :class:`~openerp.fields.Selection`
+
+    .. attribute:: parent_id
+
+        used to order records in a tree structure and enables the ``child_of``
+        operator in domains
+
+        :type: :class:`~openerp.fields.Many2one`
+
+    .. attribute:: parent_left
+
+        used with :attr:`~._parent_store`, allows faster tree structure access
+
+    .. attribute:: parent_right
+
+        see :attr:`~.parent_left`
+
+.. _reference/orm/decorators:
+
+Method decorators
+=================
+
+.. automodule:: openerp.api
+    :members: one, multi, model, depends, constrains, onchange, returns
+
+.. _reference/orm/fields:
+
+Fields
+======
+
+.. _reference/orm/fields/basic:
+
+Basic fields
+------------
+
+.. autodoc documents descriptors as attributes, even for the *definition* of
+   descriptors. As a result automodule:: openerp.fields lists all the field
+   classes as attributes without providing inheritance info or methods (though
+   we don't document methods as they're not useful for "external" devs)
+   (because we don't support pluggable field types) (or do we?)
+
+.. autoclass:: openerp.fields.Field
+
+.. autoclass:: openerp.fields.Char
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Boolean
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Integer
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Float
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Text
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Selection
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Html
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Date
+    :show-inheritance:
+    :members: today, context_today, from_string, to_string
+
+.. autoclass:: openerp.fields.Datetime
+    :show-inheritance:
+    :members: now, context_timestamp, from_string, to_string
+
+.. _reference/orm/fields/relational:
+
+Relational fields
+-----------------
+
+.. autoclass:: openerp.fields.Many2one
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.One2many
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Many2many
+    :show-inheritance:
+
+.. autoclass:: openerp.fields.Reference
+    :show-inheritance:
+
+.. _reference/orm/domains:
+
+Domains
+=======
+
+A domain is a list of criterion, each criterion being a triple (either a
+``list`` or a ``tuple``) of ``(field_name, operator, value)`` where:
+
+``field_name`` (``str``)
+    a field name of the current model, or a relationship traversal through
+    a :class:`~openerp.fields.Many2one` using dot-notation e.g. ``'street'``
+    or ``'partner_id.country'``
+``operator`` (``str``)
+    a comparison operator between the criterion's field and value.
+
+    .. todo:: list and detail operators, original list is way incomplete
+``value``
+    variable type, must be comparable (through ``operator``) to the named
+    field
+
+Domain criteria can be combined using logical operators in *prefix* form:
+
+``'&'``
+    logical *AND*, default operation to combine criteria following one
+    another. Arity 2 (uses the next 2 criteria or combinations).
+``'|'``
+    logical *OR*, arity 2.
+``'!'``
+    logical *NOT*, arity 1.
+
+    .. tip:: Mostly to negate combinations of criteria
+        :class: aphorism
+
+        Individual criterion generally have a negative form (e.g. ``=`` ->
+        ``!=``, ``<`` -> ``>=``) which is simpler than negating the positive.
+
+.. admonition:: Example
+
+    To search for partners named *ABC*, from belgium or germany, whose language
+    is not english::
+
+        [('name','=','ABC'),
+         ('language.code','!=','en_US'),
+         '|',('country_id.code','=','be'),
+             ('country_id.code','=','de')]
+
+    This domain is interpreted as:
+
+    .. code-block:: text
+
+            (name is 'ABC')
+        AND (language is NOT english)
+        AND (country is Belgium OR Germany)
+
diff --git a/doc/reference/qweb.rst b/doc/reference/qweb.rst
new file mode 100644
index 00000000000..53ca153d7d5
--- /dev/null
+++ b/doc/reference/qweb.rst
@@ -0,0 +1,35 @@
+.. _reference/qweb:
+
+====
+QWeb
+====
+
+Basics
+======
+
+.. _reference/qweb/output:
+
+data output
+-----------
+
+.. _reference/qweb/conditionals:
+
+conditionals
+------------
+
+.. _reference/qweb/loops:
+
+loops
+-----
+
+Python
+======
+
+Bundles
+-------
+
+Javascript
+==========
+
+loading
+-------
diff --git a/doc/reference/reports.rst b/doc/reference/reports.rst
new file mode 100644
index 00000000000..78211ff4e49
--- /dev/null
+++ b/doc/reference/reports.rst
@@ -0,0 +1,74 @@
+.. _reference/reports:
+
+============
+QWeb Reports
+============
+
+Paper Formats
+-------------
+
+There is a model called Paper Format allowing to define details specific to
+the PDF output.  These details include margins, header line, ... Everything
+related to the printed pdf.  Defining a paper format is not mandatory as there
+is a default one set on the company.  If you want a specific report to be
+associated to a specific paper format , just link the ir.actions.report.xml to
+it.
+
+Expressions used in Odoo report templates
+-----------------------------------------
+
+There are some magic variables used in the report rendering. The main ones are
+the following:
+
+``docs``
+    records for the current report
+``doc_ids``
+    list of ids for the ``docs`` records
+``doc_model``
+    model for teh ``docs`` records
+``time``
+    a reference to time_ from the Python standard library
+``translate_doc``
+    a function to translate a part of a report. It must be used as follow:
+
+    .. code-block:: xml
+
+        <t t-foreach="doc_ids" t-as="doc_id">
+          <t t-raw="translate_doc(doc_id, doc_model, 'partner_id.lang', account.report_invoice_document')"/>
+        </t>
+``user``
+    ``res.user`` record for the user printing the report
+``res_company``
+    record the current ``user``'s company
+
+Custom report
+-------------
+
+A generic report use the default rendering context, containing the magic
+variables as explained before. If you want a new rendering context containing
+anything you want to process your data Odoo AbstractModel, a custom module is
+needed. These reports are called "particular report".
+
+For a particular report, you have to write an Odoo Model containing a
+render_html method.  Classically, this method returns a call to the original
+**QWeb render** with a **custom rendering context**.
+
+.. code-block:: python
+
+    from openerp import api, models
+
+
+    class ParticularReport(models.AbstractModel):
+        _name = 'report.<<module.reportname>>'
+        @api.multi
+        def render_html(self, data=None):
+            report_obj = self.env['report']
+            report = report_obj._get_report_from_name('<<module.reportname>>')
+            docargs = {
+                'doc_ids': ids,
+                'doc_model': report.model,
+                'docs': self.env[report.model].browse(ids),
+            }
+            return report_obj.render('<<module.reportname>>', docargs)
+
+.. _time: https://docs.python.org/2/library/time.html
diff --git a/doc/reference/security.rst b/doc/reference/security.rst
new file mode 100644
index 00000000000..15dbd1c0c7e
--- /dev/null
+++ b/doc/reference/security.rst
@@ -0,0 +1,16 @@
+.. _reference/security:
+
+================
+Security in Odoo
+================
+
+.. _reference/security/acl:
+
+Access Control
+==============
+
+.. _reference/security/rules:
+
+Record Rules
+============
+
diff --git a/doc/reference/views.rst b/doc/reference/views.rst
new file mode 100644
index 00000000000..4a0d5da9e6d
--- /dev/null
+++ b/doc/reference/views.rst
@@ -0,0 +1,277 @@
+.. _reference/views:
+
+=====
+Views
+=====
+
+.. _reference/views/structure:
+
+Structure
+=========
+
+View objects expose a number of fields, they are optional unless specified
+otherwise)
+
+``name`` (mandatory)
+    only useful as a mnemonic/description of the view when looking for one in
+    a list of some sort
+``model``
+    the model linked to the view, if applicable (it doesn't for QWeb views)
+``priority``
+    client programs can request views by ``id``, or by ``(model, type)``. For
+    the latter, all the views for the right type and model will be looked for,
+    and the one with the lowest ``priority`` number will be returned (it is
+    the "default view").
+
+    ``priority`` also defines the order of application during :ref:`view
+    inheritance <reference/views/inheritance>`
+``arch``
+    the description of the view's layout, see
+    :ref:`reference/views/architecture`
+``groups_id``
+    :class:`~openerp.fields.Many2many` field to the groups allowed to view/use
+    the current view
+``inherit_id``
+    the current view's parent view, see :ref:`reference/views/inheritance`,
+    unset by default
+``mode``
+    inheritance mode, see :ref:`reference/views/inheritance`. If
+    ``inherit_id`` is unset the ``mode`` can only be ``primary``. If
+    ``inherit_id`` is set, ``extension`` by default but can be explicitly set
+    to ``primary``
+``application``
+    website feature defining togglable views. By default, views are always
+    applied
+
+.. _reference/views/inheritance:
+
+Inheritance
+===========
+
+View matching
+-------------
+
+* if a view is requested by ``(model, type)``, the view with the right model
+  and type, ``mode=primary`` and the lowest priority is matched
+* when a view is requested by ``id``, if its mode is not ``primary`` its
+  *closest* parent with mode ``primary`` is matched
+
+View resolution
+---------------
+
+Resolution generates the final ``arch`` for a requested/matched ``primary``
+view:
+
+#. if the view has a parent, the parent is fully resolved then the current
+   view's inheritance specs are applied
+#. if the view has no parent, its ``arch`` is used as-is
+#. the current view's children with mode ``extension`` are looked up  and their
+   inheritance specs are applied depth-first (a child view is applied, then
+   its children, then its siblings)
+
+The result of applying children views yields the final ``arch``
+
+Inheritance specs
+-----------------
+
+There are three types of inheritance specs:
+
+* An ``xpath`` element with an ``expr`` attribute. ``expr`` is an XPath_
+  expression\ [#hasclass]_ applied to the current ``arch``, the first node
+  it finds is the match
+* a ``field`` element with a ``name`` attribute, matches the first ``field``
+  with the same ``name``
+* any other element, the first element with the same name and identical
+  attributes (ignoring ``position``) is matched
+
+The inheritance spec can an optional ``position`` attribute specifhing how
+the matched node should be altered:
+
+``inside`` (default)
+    the content of the inheritance spec is appended to the matched node
+``replace``
+    the content of the inheritance spec replaces the matched node
+``after``
+    the content of the inheritance spec is added to the matched node's
+    parent, after the matched node
+``before``
+    the content of the inheritance spec is added to the matched node's
+    parent, before the matched node
+``attribute``
+    the content of the inheritance spec should be ``attribute`` elements
+    with a ``name`` attribute and an optional body:
+
+    * if the ``attribute`` element has a body, a new attributed named
+      after its ``name`` is created on the matched node with the
+      ``attribute`` element's text as value
+    * if the ``attribute`` element has no body, the attribute named after
+      its ``name`` is removed from the matched node. If no such attribute
+      exists, an error is raised
+
+A view's specs are applied sequentially.
+
+.. _reference/views/architecture:
+
+Architecture structures
+=======================
+
+.. _reference/views/list:
+
+Lists
+-----
+
+The root element of list views is ``<tree>``\ [#treehistory]_. The list view's
+root can have the following attributes:
+
+``editable``
+    by default, selecting a list view's row opens the corresponding
+    :ref:`form view <reference/views/form>`. The ``editable`` attributes makes
+    the list view itself editable in-place.
+
+    Valid values are ``top`` and ``bottom``, making *new* records appear
+    respectively at the top or bottom of the list
+``colors``
+    allows changing the color of a row's text based on the corresponding
+    record's attributes.
+
+    Defined as a mapping of colors to Python expressions. Values are of the
+    form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
+    in-order, the expression is evaluated for the record and if ``true`` the
+    corresponding color is applied to the row. If no color matches, uses the
+    default text color (black).
+
+    * ``color`` can be any valid `CSS color unit`_.
+    * ``expr`` should be a Python expression evaluated with the current
+      record's attributes as context values. Other context values are ``uid``
+      (the id of the current user) and ``current_date`` (the current date as
+      a string of the form ``yyyy-MM-dd``)
+``fonts``
+    allows changing a row's font style based on the corresponding record's
+    attributes.
+
+    The format is the same as for ``color``, but the ``color`` of each pair
+    is replaced by ``bold``, ``italic`` or ``underline``, the expression
+    evaluating to ``true`` will apply the corresponding style to the row's
+    text. Contrary to ``colors``, multiple pairs can match each record
+``create``, ``edit``, ``delete``
+    allows *dis*\ abling the corresponding action in the view by setting the
+    corresponding attribute to ``false``
+``on_write``
+    only makes sense on an ``editable`` list. Should be the name of a method
+    on the list's model. The method will be called with the ``id`` of a record
+    after having created or edited that record (in database).
+
+    The method should return a list of ids of other records to load or update.
+``string``
+    alternative translatable label for the view
+
+    .. deprecated:: 8.0
+
+        not displayed anymore
+
+.. toolbar attribute is for tree-tree views
+
+Possible children elements of the list view are:
+
+``button``
+    displays a button in a list cell
+
+    ``icon``
+        icon to use to display the button
+    ``string``
+        * if there is no ``icon``, the button's text
+        * if there is an ``icon``, ``alt`` text for the icon
+    ``type``
+        type of button, indicates how it clicking it affects Odoo:
+
+        ``workflow`` (default)
+            sends a signal to a workflow. The button's ``name`` is the
+            workflow signal, the row's record is passed as argument to the
+            signal
+        ``object``
+            call a method on the list's model. The button's ``name`` is the
+            method, which is called with the current row's record id and the
+            current context.
+
+            .. web client also supports a @args, which allows providing
+               additional arguments as JSON. Should that be documented? Does
+               not seem to be used anywhere
+
+        ``action``
+            load an execute an ``ir.actions``, the button's ``name`` is the
+            database id of the action. The context is expanded with the list's
+            model (as ``active_model``), the current row's record
+            (``active_id``) and all the records currently loaded in the list
+            (``active_ids``, may be just a subset of the database records
+            matching the current search)
+    ``name``
+        see ``type``
+    ``args``
+        see ``type``
+    ``attrs``
+        dynamic attributes based on record values.
+
+        A mapping of attributes to domains, domains are evaluated in the
+        context of the current row's record, if ``True`` the corresponding
+        attribute is set on the cell.
+
+        Possible attributes are ``invisible`` (hides the button) and
+        ``readonly`` (disables the button but still shows it)
+    ``states``
+        shorthand for ``invisible`` ``attrs``: a list of space, separated
+        states, requires that the model has a ``state`` field and that it is
+        used in the view.
+
+        Makes the button ``invisible`` if the record is *not* in one of the
+        listed states
+    ``context``
+        merged into the view's context when performing the button's Odoo call
+    ``confirm``
+        confirmation message to display (and for the user to accept) before
+        performing the button's Odoo call
+
+    .. declared but unused: help
+
+``field``
+    displays a field's value in a list cell
+
+.. _reference/views/form:
+
+Forms
+-----
+
+.. _reference/views/search:
+
+Search
+------
+
+.. _reference/views/graphs:
+
+Graphs
+------
+
+@type=row/@type=col
+
+.. _reference/views/kanban:
+
+Kanban
+------
+
+.. _reference/views/calendar:
+
+Calendar
+--------
+
+.. _reference/views/qweb:
+
+QWeb (?)
+--------
+
+.. [#hasclass] an extension function is added for simpler matching in QWeb
+               views: ``hasclass(*classes)`` matches if the context node has
+               all the specified classes
+.. [#treehistory] for historical reasons, it has its origin in tree-type views
+                  later repurposed to a more table/list-type display
+
+.. _CSS color unit: http://www.w3.org/TR/css3-color/#colorunits
+.. _XPath: http://en.wikipedia.org/wiki/XPath