From 2ad092b5e54fa39a906b38d9240e08b9800ea0da Mon Sep 17 00:00:00 2001
From: Raphael Collet <rco@openerp.com>
Date: Fri, 22 Aug 2014 17:51:20 +0200
Subject: [ADD] doc: new documentation, with training tutorials, and new
 scaffolding

---
 doc/reference/cmdline.rst    |  85 +++++++++++
 doc/reference/data.rst       | 275 +++++++++++++++++++++++++++++++++
 doc/reference/http.rst       |  27 ++++
 doc/reference/javascript.rst |   9 ++
 doc/reference/module.rst     |  80 ++++++++++
 doc/reference/orm.rst        | 353 +++++++++++++++++++++++++++++++++++++++++++
 doc/reference/qweb.rst       |  35 +++++
 doc/reference/reports.rst    |  74 +++++++++
 doc/reference/security.rst   |  16 ++
 doc/reference/views.rst      | 277 +++++++++++++++++++++++++++++++++
 10 files changed, 1231 insertions(+)
 create mode 100644 doc/reference/cmdline.rst
 create mode 100644 doc/reference/data.rst
 create mode 100644 doc/reference/http.rst
 create mode 100644 doc/reference/javascript.rst
 create mode 100644 doc/reference/module.rst
 create mode 100644 doc/reference/orm.rst
 create mode 100644 doc/reference/qweb.rst
 create mode 100644 doc/reference/reports.rst
 create mode 100644 doc/reference/security.rst
 create mode 100644 doc/reference/views.rst

(limited to 'doc/reference')

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
-- 
cgit v1.2.3


From f620a6767277f8ab98366308accfe4c18a0e37f8 Mon Sep 17 00:00:00 2001
From: Raphael Collet <rco@openerp.com>
Date: Mon, 25 Aug 2014 11:30:12 +0200
Subject: [IMP] doc/howtos/backend: add a small section on how to start the
 server

---
 doc/reference/cmdline.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/reference')

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index dcedbe03eba..5999f9fa1ad 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -1,7 +1,7 @@
 .. _reference/cmdline:
 
 ===============================
-Command-line interface: oodo.py
+Command-line interface: odoo.py
 ===============================
 
 .. _reference/cmdline/server:
-- 
cgit v1.2.3


From 442dec24966acaaaf1460f981227c44e65f1fe7f Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Mon, 25 Aug 2014 13:48:34 +0200
Subject: [ADD] reinstate form guidelines

---
 doc/reference/views.rst | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/reference')

diff --git a/doc/reference/views.rst b/doc/reference/views.rst
index 4a0d5da9e6d..da9511ac241 100644
--- a/doc/reference/views.rst
+++ b/doc/reference/views.rst
@@ -240,6 +240,8 @@ Possible children elements of the list view are:
 Forms
 -----
 
+
+
 .. _reference/views/search:
 
 Search
-- 
cgit v1.2.3


From e6b56412a04aae8cfe04218edb967dbcb314a7c6 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Tue, 26 Aug 2014 14:59:43 +0200
Subject: [ADD] views documentation

---
 doc/reference/data.rst       |   2 +
 doc/reference/javascript.rst |   5 +
 doc/reference/qweb.rst       |   2 +
 doc/reference/views.rst      | 684 ++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 683 insertions(+), 10 deletions(-)

(limited to 'doc/reference')

diff --git a/doc/reference/data.rst b/doc/reference/data.rst
index 6e9a004f9ac..90121bfc03e 100644
--- a/doc/reference/data.rst
+++ b/doc/reference/data.rst
@@ -199,6 +199,8 @@ Groups
 ``id``
     the menu item's :term:`external id`
 
+.. _reference/data/template:
+
 ``template``
 ------------
 
diff --git a/doc/reference/javascript.rst b/doc/reference/javascript.rst
index 668543a906d..ae7b02c63a4 100644
--- a/doc/reference/javascript.rst
+++ b/doc/reference/javascript.rst
@@ -7,3 +7,8 @@ Widgets
 
 RPC
 ===
+
+.. _reference/javascript/client:
+
+Web Client
+==========
diff --git a/doc/reference/qweb.rst b/doc/reference/qweb.rst
index 53ca153d7d5..c993c0c3c22 100644
--- a/doc/reference/qweb.rst
+++ b/doc/reference/qweb.rst
@@ -28,6 +28,8 @@ Python
 Bundles
 -------
 
+.. _reference/qweb/javascript:
+
 Javascript
 ==========
 
diff --git a/doc/reference/views.rst b/doc/reference/views.rst
index da9511ac241..cf4e5e8a804 100644
--- a/doc/reference/views.rst
+++ b/doc/reference/views.rst
@@ -115,6 +115,16 @@ A view's specs are applied sequentially.
 Architecture structures
 =======================
 
+Although they are all expressed as XML and have common points (most commonly
+the presence of ``<field>`` elements), each view has its own ``arch``
+structure with a specific root elements, semantics and affordances.
+
+Most views accept the ``create``, ``edit`` and ``delete`` attributes on their
+root element, when applicable this is used to disable the corresponding action
+from the view (hide the relevant buttons or avoid displaying an interface to
+perform it). May be set to ``true`` or ``false``. Setting them to ``true``
+will override their auto-generation from access-rights.
+
 .. _reference/views/list:
 
 Lists
@@ -129,7 +139,13 @@ root can have the following attributes:
     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
+    respectively at the top or bottom of the list.
+
+    The architecture for the inline :ref:`form view <reference/views/form>` is
+    derived from the list view. Most attributes valid on a :ref:`form view
+    <reference/views/form>`'s fields and buttons are thus accepted by list
+    views although they may not have any meaning if the list view is
+    non-editable
 ``colors``
     allows changing the color of a row's text based on the corresponding
     record's attributes.
@@ -173,6 +189,8 @@ root can have the following attributes:
 
 Possible children elements of the list view are:
 
+.. _reference/views/list/button:
+
 ``button``
     displays a button in a list cell
 
@@ -233,47 +251,693 @@ Possible children elements of the list view are:
     .. declared but unused: help
 
 ``field``
-    displays a field's value in a list cell
+    defines a column where the corresponding field should be displayed for
+    each record. Can use the following attributes:
+
+    ``name``
+        the name of the field to display in the current model. A given name
+        can only be used once per view
+    ``string``
+        the title of the field's column (by default, uses the ``string`` of
+        the model's field)
+    ``invisible``
+        fetches and stores the field, but doesn't display the column in the
+        table. Necessary for fields which shouldn't be displayed but are
+        used by e.g. ``@colors``
+    ``groups``
+        lists the groups which should be able to see the field
+    ``widget``
+        alternate representations for a field's display. Possible list view
+        values are:
+
+        ``progressbar``
+            displays ``float`` fields as a progress bar.
+        ``many2onebutton``
+            replaces the m2o field's value by a checkmark if the field is
+            filled, and a cross if it is not
+        ``handle``
+            for ``sequence`` fields, instead of displaying the field's value
+            just displays a dra&drop icon
+    ``sum``, ``avg``
+        displays the corresponding aggregate at the bottom of the column. The
+        aggregation is only computed on *currently displayed* records. The
+        aggregation operation must match the corresponding field's
+        ``group_operator``
+    ``attrs``
+        dynamic attributes based on record values. Only effects the current
+        field, so e.g. ``invisible`` will hide the field but leave the same
+        field of other records visible, it will not hide the column itself
+
+    .. note:: if the list view is ``editable``, any field attribute from the
+              :ref:`form view <reference/views/form>` is also valid and will
+              be used when setting up the inline form view
 
 .. _reference/views/form:
 
 Forms
 -----
 
+Form views are used to display the data from a single record. Their root
+element is ``<form>``. They are composed of regular HTML_ with additional
+structural and semantic components.
+
+Structural components
+'''''''''''''''''''''
+
+Structural components provide structure or "visual" features with little
+logic. They are used as elements or sets of elements in form views.
+
+``notebook``
+  defines a tabbed section. Each tab is defined through a ``page`` child
+  element. Pages can have the following attributes:
+
+  ``string`` (required)
+    the title of the tab
+  ``accesskey``
+    an HTML accesskey_
+  ``attrs``
+    standard dynamic attributes based on record values
+
+``group``
+  used to define column layouts in forms. By default, groups define 2 columns
+  and most direct children of groups take a single column. ``field`` direct
+  children of groups display a label by default, and the label and the field
+  itself have a colspan of 1 each.
+
+  The number of columns in a ``group`` can be customized using the ``col``
+  attribute, the number of columns taken by an element can be customized using
+  ``colspan``.
+
+  Children are laid out horizontally (tries to fill the next column before
+  changing row).
+
+  Groups can have a ``string`` attribute, which is displayed as the group's
+  title
+``newline``
+  only useful within ``group`` elements, ends the current row early and
+  immediately switches to a new row (without filling any remaining column
+  beforehand)
+``separator``
+  small horizontal spacing, with a ``string`` attribute behaves as a section
+  title
+``sheet``
+  can be used as a direct child to ``form`` for a narrower and more responsive
+  form layout
+``header``
+  combined with ``sheet``, provides a full-width location above the sheet
+  itself, generally used to display workflow buttons and status widgets
+
+Semantic components
+'''''''''''''''''''
+
+Semantic components tie into and allow interaction with the Odoo
+system. Available semantic components are:
 
+``button``
+  call into the Odoo system, similar to :ref:`list view buttons
+  <reference/views/list/button>`
+``field``
+  renders (and allow edition of, possibly) a single field of the current
+  record. Possible attributes are:
+
+  ``name`` (mandatory)
+    the name of the field to render
+  ``widget``
+    fields have a default rendering based on their type
+    (e.g. :class:`~openerp.fields.Char`,
+    :class:`~openerp.fields.Many2one`). The ``widget`` attributes allows using
+    a different rendering method and context.
+
+    .. todo:: list of widgets
+
+       & options & specific attributes (e.g. widget=statusbar
+       statusbar_visible statusbar_colors clickable)
+  ``options``
+    JSON object specifying configuration option for the field's widget
+    (including default widgets)
+  ``class``
+    HTML class to set on the generated element, common field classes are:
+
+    ``oe_inline``
+      prevent the usual line break following fields
+    ``oe_left``, ``oe_right``
+      floats_ the field to the corresponding direction
+    ``oe_read_only``, ``oe_edit_only``
+      only displays the field in the corresponding form mode
+    ``oe_no_button``
+      avoids displaying the navigation button in a
+      :class:`~openerp.fields.Many2one`
+    ``oe_avatar``
+      for image fields, displays images as "avatar" (square, 90x90 maximum
+      size, some image decorations)
+  ``groups``
+    only displays the field for specific users
+  ``on_change``
+    calls the specified method when this field's value is edited, can generate
+    update other fields or display warnings for the user
 
-.. _reference/views/search:
-
-Search
-------
+    .. deprecated:: 8.0
 
-.. _reference/views/graphs:
+       Use :func:`openerp.api.onchange` on the model
+
+  ``attrs``
+    dynamic meta-parameters based on record values
+  ``domain``
+    for relational fields only, filters to apply when displaying existing
+    records for selection
+  ``context``
+    for relational fields only, context to pass when fetching possible values
+  ``readonly``
+    display the field in both readonly and edition mode, but never make it
+    editable
+  ``required``
+    generates an error and prevents saving the record if the field doesn't
+    have a value
+  ``nolabel``
+    don't automatically display the field's label, only makes sense if the
+    field is a direct child of a ``group`` element
+  ``placeholder``
+    help message to display in *empty* fields. Can replace field labels in
+    complex forms. *Should not* be an example of data as users are liable to
+    confuse placeholder text with filled fields
+  ``mode``
+    for :class:`~openerp.fields.One2many`, display mode (view type) to use for
+    the field's linked records. One of ``tree``, ``form``, ``kanban`` or
+    ``graph``. The default is ``tree`` (a list display)
+  ``help``
+    tooltip displayed for users when hovering the field or its label
+  ``filename``
+    for binary fields, name of the related field providing the name of the
+    file
+  ``password``
+    indicates that a :class:`~openerp.fields.Char` field stores a password and
+    that its data shouldn't be displayed
+
+.. todo:: classes for forms
+
+.. todo:: widgets?
+
+.. _reference/views/graph:
 
 Graphs
 ------
 
-@type=row/@type=col
+The graph view is used to visualize aggregations over a number of records or
+record groups. Its root element is ``<graph>`` which can take the following
+attributes:
+
+``type``
+  one of ``bar`` (default), ``pie``, ``line`` and ``pivot``, the type of graph
+  to use (``pivot`` technically isn't a graph type, it displays the
+  aggregation as a `pivot table`_)
+``stacked``
+  only used for ``bar`` charts. If present and set to ``True``, stacks bars
+  within a group
+
+The only allowed element within a graph view is ``field`` which can have the
+following attributes:
+
+``name`` (required)
+  the name of a field to use in a graph view. If used for grouping (rather
+  than aggregating), can be augmented with a
+  :ref:`reference/views/graph/functions`
+
+``type``
+  indicates whether the field should be used as a grouping criteria or as an
+  aggregated value within a group. Possible values are:
+
+  ``row`` (default)
+    groups by the specified field. All graph types support at least one level
+    of grouping, some may support more. For pivot tables, each group gets its
+    own row.
+  ``col``
+    only used by pivot tables, creates column-wise groups
+  ``measure``
+    field to aggregate within a group
+
+.. warning::
+
+   graph view aggregations are performed on database content, non-stored
+   function fields can not be used in graph views
+
+.. _reference/views/graph/functions:
+
+Grouping function
+'''''''''''''''''
+
+Field names in graph views can be postfixed with a grouping function using the
+form :samp:`{field_name}:{function}`. As of 8.0, only date and datetime fields
+support grouping functions. The available grouping functions are ``day``,
+``week``, ``month``, ``quarter`` and ``year``. By default, date and datetime
+fields are grouped month-wise.
 
 .. _reference/views/kanban:
 
 Kanban
 ------
 
+The kanban view is a `kanban board`_ visualisation: it displays records as
+"cards", halfway between a :ref:`list view <reference/views/list>` and a
+non-editable :ref:`form view <reference/views/form>`. Records may be grouped
+in columns for use in workflow visualisation or manipulation (e.g. tasks or
+work-progress management), or ungrouped (used simply to visualize records).
+
+The root element of the Kanban view is ``<kanban>``, it can use the following
+attributes:
+
+``default_group_by``
+  whether the kanban view should be grouped if no grouping is specified via
+  the action or the current research. Should be the name of the field to group
+  by when no grouping is otherwise specified
+``default_order``
+  cards sorting order used if the user has not already sorted the records (via
+  the list view)
+``class``
+  adds HTML classes to the root HTML element of the Kanban view
+``quick_create``
+  whether it should be possible to create records without switching to the
+  form view. By default, ``quick_create`` is enabled when the Kanban view is
+  grouped, and disabled when not.
+
+  Set to ``true`` to always enable it, and to ``false`` to always disable it.
+
+Possible children of the view element are:
+
+``field``
+  declares fields to aggregate or to use in kanban *logic*. If the field is
+  simply displayed in the kanban view, it does not need to be pre-declared.
+
+  Possible attributes are:
+
+  ``name`` (required)
+    the name of the field to fetch
+  ``sum``, ``avg``, ``min``, ``max``, ``count``
+    displays the corresponding aggregation at the top of a kanban column, the
+    field's value is the label of the aggregation (a string). Only one
+    aggregate operation per field is supported.
+
+``templates``
+  defines a list of :ref:`reference/qweb` templates. Cards definition may be
+  split into multiple templates for clarity, but kanban views *must* define at
+  least one root template ``kanban-box``, which will be rendered once for each
+  record.
+
+  The kanban view uses mostly-standard :ref:`javascript qweb
+  <reference/qweb/javascript>` and provides the following context variables:
+
+  ``instance``
+    the current :ref:`reference/javascript/client` instance
+  ``widget``
+    the current :js:class:`KanbanRecord`, can be used to fetch some
+    meta-information. These methods are also available directly in the
+    template context and don't need to be accessed via ``widget``
+  ``record``
+    an object with all the requested fields as its attributes. Each field has
+    two attributes ``value`` and ``raw_value``, the former is formatted
+    according to current user parameters, the latter is the direct value from
+    a :meth:`~openerp.models.Model.read`
+  ``read_only_mode``
+    self-explanatory
+
+
+    .. rubric:: buttons and fields
+
+    While most of the Kanban templates are standard :ref:`reference/qweb`, the
+    Kanban view processes ``field``, ``button`` and ``a`` elements specially:
+
+    * by default fields are replaced by their formatted value, unless they
+      match specific kanban view widgets
+
+      .. todo:: list widgets?
+
+    * buttons and links with a ``type`` attribute become perform Odoo-related
+      operations rather than their standard HTML function. Possible types are:
+
+      ``action``, ``object``
+        standard behavior for :ref:`Odoo buttons
+        <reference/views/list/button>`, most attributes relevant to standard
+        Odoo buttons can be used.
+      ``open``
+        opens the card's record in the form view in read-only mode
+      ``edit``
+        opens the card's record in the form view in editable mode
+      ``delete``
+        deletes the card's record and removes the card
+
+    .. todo::
+
+       * kanban-specific CSS
+       * kanban structures/widgets (vignette, details, ...)
+
+Javascript API
+''''''''''''''
+
+.. js:class:: KanbanRecord
+
+   :js:class:`Widget` handling the rendering of a single record to a
+   card. Available within its own rendering as ``widget`` in the template
+   context.
+
+   .. js:function:: kanban_color(raw_value)
+
+      Converts a color segmentation value to a kanban color class
+      :samp:`oe_kanban_color_{color_index}`. The built-in CSS provides classes
+      up to a ``color_index`` of 9.
+
+   .. js:function:: kanban_getcolor(raw_value)
+
+      Converts a color segmentation value to a color index (between 0 and 9 by
+      default). Color segmentation values can be either numbers or strings.
+
+   .. js:function:: kanban_image(model, field, id[, cache][, options])
+
+      Generates the URL to the specified field as an image access.
+
+      :param String model: model hosting the image
+      :param String field: name of the field holding the image data
+      :param id: identifier of the record contaning the image to display
+      :param Number cache: caching duration (in seconds) of the browser
+                           default should be overridden. ``0`` disables
+                           caching entirely
+      :returns: an image URL
+
+   .. js:function:: kanban_text_ellipsis(string[, size=160])
+
+      clips text beyond the specified size and appends an ellipsis to it. Can
+      be used to display the initial part of potentially very long fields
+      (e.g. descriptions) without the risk of unwieldy cards
+
 .. _reference/views/calendar:
 
 Calendar
 --------
 
+Calendar views display records as events in a daily, weekly or monthly
+calendar. Their root element is ``<calendar>``. Available attributes on the
+calendar view are:
+
+``date_start`` (required)
+    name of the record's field holding the start date for the event
+``date_end``
+    name of the record's field holding the end date for the event, if
+    ``date_end`` is provided records become movable (via drag and drop)
+    directly in the calendar
+``date_delay``
+    alternative to ``date_end``, provides the duration of the event instead of
+    its end date
+
+    .. todo:: what's the unit? Does it allow moving the record?
+
+``color``
+    name of a record field to use for *color segmentation*. Records in the
+    same color segment are allocated the same highlight color in the calendar,
+    colors are allocated semi-randomly.
+``event_open_popup``
+    opens the event in a dialog instead of switching to the form view, enabled
+    by default
+``quick_add``
+    enables quick-event creation on click: only asks the user for a ``name``
+    and tries to create a new event with just that and the clicked event
+    time. Falls back to a full form dialog if the quick creation fails
+``display``
+    format string for event display, field names should be within brackets
+    ``[`` and ``]``
+``all_day``
+    name of a boolean field on the record indicating whether the corresponding
+    event is flagged as day-long (and duration is irrelevant)
+
+
+.. todo::
+
+   what's the purpose of ``<field>`` inside a calendar view?
+
+.. todo::
+
+   calendar code is an unreadable mess, no idea what these things are:
+
+   * ``attendee``
+   * ``avatar_model``
+   * ``use_contacts``
+
+   calendar code also seems to refer to multiple additional attributes of
+   unknown purpose
+
+.. _reference/views/gantt:
+
+Gantt
+-----
+
+Gantt views appropriately display Gantt charts (for scheduling).
+
+The root element of gantt views is ``<gantt/>``, it has no children but can
+take the following attributes:
+
+``date_start`` (required)
+  name of the field providing the start datetime of the event for each
+  record.
+``date_stop``
+  name of the field providing the end duration of the event for each
+  record. Can be replaced by ``date_delay``. One (and only one) of
+  ``date_stop`` and ``date_delay`` must be provided.
+
+  If the field is ``False`` for a record, it's assumed to be a "point event"
+  and the end date will be set to the start date
+``date_delay``
+  name of the field providing the duration of the event
+``progress``
+  name of a field providing the completion percentage for the record's event,
+  between 0 and 100
+``default_group_by``
+  name of a field to group tasks by
+
+.. previously documented content which don't seem to be used anymore:
+
+   * string
+   * day_length
+   * color
+   * mode
+   * date_string
+   * <level>
+   * <field>
+   * <html>
+
+.. _reference/views/diagram:
+
+Diagram
+-------
+
+The diagram view can be used to display directed graphs of records. The root
+element is ``<diagram>`` and takes no attributes.
+
+Possible children of the diagram view are:
+
+``node`` (required, 1)
+    Defines the nodes of the graph. Its attributes are:
+
+    ``object``
+      the node's Odoo model
+    ``shape``
+      conditional shape mapping similar to colors and fonts in :ref:`the list
+      view <reference/views/list>`. The only valid shape is ``rectangle`` (the
+      default shape is an ellipsis)
+    ``bgcolor``
+      same as ``shape``, but conditionally maps a background color for
+      nodes. The default background color is white, the only valid alternative
+      is ``grey``.
+``arrow`` (required, 1)
+    Defines the directed edges of the graph. Its attributes are:
+
+    ``object`` (required)
+      the edge's Odoo model
+    ``source`` (required)
+      :class:`~openerp.fields.Many2one` field of the edge's model pointing to
+      the edge's source node record
+    ``destination`` (required)
+      :class:`~openerp.fields.Many2one` field of the edge's model pointing to
+      the edge's destination node record
+    ``label``
+      Python list of attributes (as quoted strings). The corresponding
+      attributes's values will be concatenated and displayed as the edge's
+      label
+
+``label``
+    Explanatory note for the diagram, the ``string`` attribute defines the
+    note's content. Each ``label`` is output as a paragraph in the diagram
+    header, easily visible but without any special emphasis.
+
+.. _reference/views/search:
+
+Search
+------
+
+Search views are a break from previous view types in that they don't display
+*content*: although they apply to a specific model, they are used to filter
+other view's content (generally aggregated views
+e.g. :ref:`reference/views/list` or :ref:`reference/views/graph`). Beyond that
+difference in use case, they are defined the same way.
+
+The root element of search views is ``<search>``. It takes no attributes.
+
+.. @string is not displayed anywhere, should be removed
+
+Possible children elements of the search view are:
+
+``field``
+    fields define domains or contexts with user-provided values. When search
+    domains are generated, field domains are composed with one another and
+    with filters using **AND**.
+
+    Fields can have the following attributes:
+
+    ``name``
+        the name of the field to filter on
+    ``string``
+        the field's label
+    ``operator``
+        by default, fields generate domains of the form :samp:`[({name},
+        {operator}, {provided_value})]` where ``name`` is the field's name and
+        ``provided_value`` is the value provided by the user, possibly
+        filtered or transformed (e.g. a user is expected to provide the
+        *label* of a selection field's value, not the value itself).
+
+        The ``operator`` attribute allows overriding the default operator,
+        which depends on the field's type (e.g. ``=`` for float fields but
+        ``ilike`` for char fields)
+    ``filter_domain``
+        complete domain to use as the field's search domain, can use a
+        ``self`` variable to inject the provided value in the custom
+        domain. Can be used to generate significantly more flexible domains
+        than ``operator`` alone (e.g. searches on multiple fields at once)
+
+        If both ``operator`` and ``filter_domain`` are provided,
+        ``filter_domain`` takes precedence.
+    ``context``
+        allows adding context keys, including the user-provided value (which
+        as for ``domain`` is available as a ``self`` variable). By default,
+        fields don't generate domains.
+
+        .. note:: the domain and context are inclusive and both are generated
+                  if if a ``context`` is specified. To only generate context
+                  values, set ``filter_domain`` to an empty list:
+                  ``filter_domain="[]"``
+    ``groups``
+        make the field only available to specific users
+    ``widget``
+        use specific search widget for the field (the only use case in
+        standard Odoo 8.0 is a ``selection`` widget for
+        :class:`~openerp.fields.Many2one` fields)
+    ``domain``
+        if the field can provide an auto-completion
+        (e.g. :class:`~openerp.fields.Many2one`), filters the possible
+        completion results.
+
+``filter``
+    a filter is a predefined toggle in the search view, it can only be enabled
+    or disabled. Its main purposes are to add data to the search context (the
+    context passed to the data view for searching/filtering), or to append new
+    sections to the search filter.
+
+    Filters can have the following attributes:
+
+    ``string`` (required)
+        the label of the filter
+    ``domain``
+        an Odoo :ref:`domain <reference/orm/domains>`, will be appended to the
+        action's domain as part of the search domain
+    ``context``
+        a Python dictionary, merged into the action's domain to generate the
+        search domain
+    ``name``
+        logical name for the filter, can be used to :ref:`enable it by default
+        <reference/views/search/defaults>`, can also be used as
+        :ref:`inheritance hook <reference/views/inheritance>`
+    ``help``
+        a longer explanatory text for the filter, may be displayed as a
+        tooltip
+    ``groups``
+        makes a filter only available to specific users
+    ``icon``
+        an icon to display next to the label, if there's sufficient space
+
+        .. deprecated:: 7.0
+
+    .. tip::
+
+       .. versionadded:: 7.0
+
+       Sequences of filters (without non-filters separating them) are treated
+       as inclusively composited: they will be composed with ``OR`` rather
+       than the usual ``AND``, e.g.
+
+       .. code-block:: xml
+
+          <filter domain="[('state', '=', 'draft')]"/>
+          <filter domain="[('state', '=', 'done')]"/>
+
+       if both filters are selected, will select the records whose ``state``
+       is ``draft`` or ``done``, but
+
+       .. code-block:: xml
+
+          <filter domain="[('state', '=', 'draft')]"/>
+          <separator/>
+          <filter domain="[('delay', '<', 15)]"/>
+
+       if both filters are selected, will select the records whose ``state``
+       is ``draft`` **and** ``delay`` is below 15.
+
+``separator``
+    can be used to separates groups of filters in simple search views
+``group``
+    can be used to separate groups of filters, more readable than
+    ``separator`` in complex search views
+
+.. _reference/views/search/defaults:
+
+Search defaults
+'''''''''''''''
+
+Search fields and filters can be configured through the action's ``context``
+using :samp:`search_default_{name}` keys. For fields, the value should be the
+value to set in the field, for filters it's a boolean value. For instance,
+assuming ``foo`` is a field and ``bar`` is a filter an action context of::
+
+  {
+    'search_default_foo': 'acro',
+    'search_default_bar': 1
+  }
+
+will automatically enable the ``bar`` filter and search the ``foo`` field for
+*acro*.
+
 .. _reference/views/qweb:
 
-QWeb (?)
---------
+QWeb
+----
+
+QWeb views are standard :ref:`reference/qweb` templates inside a view's
+``arch``. They don't have a specific root element.
+
+A QWeb view can only contain a single template\ [#template_inherit]_, and the
+template's name *must* match the view's complete (including module name)
+:term:`external id`.
+
+:ref:`reference/data/template` should be used as a shortcut to define QWeb
+views.
 
 .. [#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
+.. [#template_inherit] or no template if it's an inherited view, then :ref:`it
+                       should only contain xpath elements
+                       <reference/views/inheritance>`
 
+.. _accesskey: http://www.w3.org/TR/html5/editing.html#the-accesskey-attribute
 .. _CSS color unit: http://www.w3.org/TR/css3-color/#colorunits
+.. _floats: https://developer.mozilla.org/en-US/docs/Web/CSS/float
+.. _HTML: http://en.wikipedia.org/wiki/HTML
+.. _kanban board: http://en.wikipedia.org/wiki/Kanban_board
+.. _pivot table: http://en.wikipedia.org/wiki/Pivot_table
 .. _XPath: http://en.wikipedia.org/wiki/XPath
-- 
cgit v1.2.3


From afcb89ab3aa8af4fbd46d84f7b2fb0a8bce5b7d7 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Fri, 29 Aug 2014 13:39:07 +0200
Subject: [ADD] port security reference doc

---
 doc/reference/cmdline.rst  |  6 ++--
 doc/reference/data.rst     |  3 +-
 doc/reference/module.rst   | 17 ++-------
 doc/reference/security.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 93 insertions(+), 21 deletions(-)

(limited to 'doc/reference')

diff --git a/doc/reference/cmdline.rst b/doc/reference/cmdline.rst
index 5999f9fa1ad..140405d0037 100644
--- a/doc/reference/cmdline.rst
+++ b/doc/reference/cmdline.rst
@@ -17,13 +17,11 @@ Running the server
 
 .. option:: -i <modules>, --init=<modules>
 
-    comma-separated list of modules to :ref:`install
-    <reference/module/lifecycle/install>` before running the server.
+    comma-separated list of modules to 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.
+    comma-separated list of modules to update before running the server.
 
 .. option:: --addons-path <directories>
 
diff --git a/doc/reference/data.rst b/doc/reference/data.rst
index 90121bfc03e..bd98ded3e8b 100644
--- a/doc/reference/data.rst
+++ b/doc/reference/data.rst
@@ -52,8 +52,7 @@ following attributes:
 ``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.
+    in update mode whether the record should be created if it doesn't exist
 
     Requires an :term:`external id`, defaults to ``True``.
 
diff --git a/doc/reference/module.rst b/doc/reference/module.rst
index 933b263f7ba..14e7847f1da 100644
--- a/doc/reference/module.rst
+++ b/doc/reference/module.rst
@@ -2,6 +2,8 @@
 Modules
 =======
 
+
+
 .. _reference/module/manifest:
 
 Manifest
@@ -60,21 +62,6 @@ Available manifest fields are:
     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/security.rst b/doc/reference/security.rst
index 15dbd1c0c7e..72742f0639c 100644
--- a/doc/reference/security.rst
+++ b/doc/reference/security.rst
@@ -4,13 +4,101 @@
 Security in Odoo
 ================
 
+Aside from manually managing access using custom code, Odoo provides two main
+data-driven mechanisms to manage or restrict access to data.
+
+Both mechanisms are linked to specific users through *groups*: a user belongs
+to any number of groups, and security mechanisms are associated to groups,
+thus applying security mechamisms to users.
+
 .. _reference/security/acl:
 
 Access Control
 ==============
 
+Managed by the ``ir.model.access`` records, defines access to a whole model.
+
+Each access control has a model to which it grants permissions, the
+permissions it grants and optionally a group.
+
+Access controls are additive, for a given model a user has access all
+permissions granted to any of its groups: if the user belongs to group *A*
+which allows writing and group *B* which allows deleting, he can both write
+and delete.
+
+If no group is specified, the access control applies to all users, otherwise
+it only applies to the users belonging to the specific group.
+
+Available permissions are creation (``perm_create``), searching and reading
+(``perm_read``), updating existing records (``perm_write``) and deleting
+existing records (``perm_unlink``)
+
 .. _reference/security/rules:
 
 Record Rules
 ============
 
+Record rules are conditions that records must satisfy for an operation
+(create, read, update or delete) to be allowed. It is applied record-by-record
+after access control has been applied.
+
+A record rule has:
+
+* a model on which it applies
+* a set of permissions to which it applies (e.g. if ``perm_read`` is set, the
+  rule will only be checked when reading a record)
+* a set of user groups to which the rule applies, if no group is specified
+  the rule is *global*
+* a :ref:`domain <reference/orm/domains>` used to check whether a given record
+  matches the rule (and is accessible) or does not (and is not accessible).
+  The domain is evaluated with two variables in context: ``user`` is the
+  current user's record and ``time`` is the `time module`_
+
+Global rules and group rules (rules restricted to specific groups versus
+groups applying to all users) are used quite differently:
+
+* Global rules are subtractive, they *must all* be matched for a record to be
+  accessible
+* Group rules are additive, if *any* of them matches (and all global rules
+  match) then the record is accessible
+
+This means the first *group rule* restricts access, but any further
+*group rule* expands it, while *global rules* can only ever restrict access
+(or have no effect).
+
+.. warning:: record rules do not apply to the Administrator user
+    :class: aphorism
+
+    although access rules do
+
+Field Access
+============
+
+.. versionadded:: 7.0
+
+An ORM :class:`~openerp.fields.Field` can have a ``groups`` attribute
+providing a list of groups (as a comma-separated string of
+:term:`external identifiers`).
+
+If the current user is not in one of the listed groups, he will not have
+access to the field:
+
+* restricted fields are automatically removed from requested views
+* restricted fields are removed from :meth:`~openerp.models.Model.fields_get`
+  responses
+* attempts to (explicitly) read from or write to restricted fields results in
+  an access error
+
+.. todo::
+
+    field access groups apply to administrator in fields_get but not in
+    read/write...
+
+Workflow transition rules
+=========================
+
+Workflow transitions can be restricted to a specific group. Users outside the
+group can not trigger the transition.
+
+.. _foo: http://google.com
+.. _time module: https://docs.python.org/2/library/time.html
-- 
cgit v1.2.3


From cccd3c888fdcbd56e2e1a33ce50b0d61f96a92a9 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Mon, 1 Sep 2014 11:54:34 +0200
Subject: [ADD] openerp.http reference doc

* fix some docstrings so they can be autodoc'd
* intersphinx mapping (and links to) werkzeug and python
---
 doc/reference/http.rst | 68 +++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 62 insertions(+), 6 deletions(-)

(limited to 'doc/reference')

diff --git a/doc/reference/http.rst b/doc/reference/http.rst
index 6459e2bbd1b..c179691c4cb 100644
--- a/doc/reference/http.rst
+++ b/doc/reference/http.rst
@@ -12,16 +12,72 @@ Routing
 Request
 =======
 
+The request object is automatically set on :data:`openerp.http.request` at
+the start of the request
+
+.. autoclass:: openerp.http.WebRequest
+    :members:
+    :member-order: bysource
+.. autoclass:: openerp.http.HttpRequest
+    :members:
+.. autoclass:: openerp.http.JsonRequest
+    :members:
+
 Response
 ========
 
-JSON-RPC
-========
+.. autoclass:: openerp.http.Response
+    :members:
+    :member-order: bysource
+
+    .. maybe set this to document all the fine methods on Werkzeug's Response
+       object? (it works)
+       :inherited-members:
 
 .. _reference/http/controllers:
 
-Extension: controllers
-======================
+Controllers
+===========
+
+Controllers need to provide extensibility, much like
+:class:`~openerp.models.Model`, but can't use the same mechanism as the
+pre-requisites (a database with loaded modules) may not be available yet (e.g.
+no database created, or no database selected).
+
+Controllers thus provide their own extension mechanism, separate from that of
+models:
+
+Controllers are created by :ref:`inheriting <python:tut-inheritance>` from
+
+.. autoclass:: openerp.http.Controller
+
+and defining methods decorated with :func:`~openerp.http.route`::
+
+    class MyController(openerp.http.Controller):
+        @route('/some_url', auth='public')
+        def handler(self):
+            return stuff()
+
+To *override* a controller, :ref:`inherit <python:tut-inheritance>` from its
+class and override relevant methods::
+
+    class Extension(MyController):
+        @route()
+        def handler(self):
+            do_before()
+            return super(Extension, self).handler()
+
+* decorating with :func:`~openerp.http.route` is necessary to keep the method
+  (and route) visible: if the method is redefined without decorating, it
+  will be "unpublished"
+* the decorators of all methods are combined, if the overriding method's
+  decorator has no argument all previous ones will be kept, any provided
+  argument will override previously defined ones e.g.::
+
+    class Restrict(MyController):
+        @route(auth='user')
+        def handler(self):
+            return super(Restrict, self).handler()
 
-.. this should be about inheritance/extension, do web controllers still do
-   anything else nowadays?
+  will change ``/some_url`` from public authentication to user (requiring a
+  log-in)
-- 
cgit v1.2.3