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

1 files changed, 353 insertions, 0 deletions

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)
+