Supplement README.rst

README.rst

 Analytic Structure
 ==================
 
+What is it ?
+------------
+
+The module provides a way of defining dynamic relationships between objects.
+We use the following concepts:
+
+- Dimensions, represented by ``analytic.dimension``
+- Structure, represented by ``analytic.structure``
+- Codes, represented by ``analytic.code``
+
+These objects can be seen in ``Technical >> Analytics`` under ``Settings``.
+
+Dimensions act as labels for data points that can be used to perform analyses.
+Structures define mappings between models and dimensions, they can be configured through the *Settings* menu.
+Codes are the objects that are bound to instances of dimension models, they allow us to define dynamic relationships.
+
+Example: Your company has several product lines and you would like to analyse expenses related to these product lines in your accounting system.
+You would then define a *product line* dimension and some structures that bind the *product line* dimension to ``product.product``, ``invoice.line``, ``account.move.line`` models.
+
+How does it work ?
+------------------
+
+Analytic Structure provides the ``MetaAnalytic`` metaclass (see MetaAnalytic_) that injects new behaviors into Odoo models.
+Dimension models and models that define analytic fields must use ``MetaAnalytic`` and define various class attributes.
+
+A dimension model is declared with the ``_dimension`` attribute (see AnalyticDimensions_).
+The metaclass automatically creates ``analytic.dimension`` records for each dimension model.
+Once a model is declared as a dimension, every new instance will automatically create a new ``analytic.code`` record that points to the relevant ``analytic.dimension`` record.
+
+A model that is declared with the ``_analytic`` attribute (see AnalyticFields_) can reference dimension objects.
+The ``MetaAnalytic`` will automatically create a number of M2O fields that point to analytic codes.
+The number of fields that will be added depends on the configuration (See ConfigureAnalyticFields_).
+They are named with a predefined prefix and a number or slot eg. ``a1_id``, ``a2_id``, ``a3_id``, ...
+
+These analytic fields will be displayed in views with the names of the dimensions they point to thanks to view manipulation magic.
+
+Schematic::
+ | AnalyticModel     Code        DimensionModel     Dimension
+ | -----             ----        --------------     ---------
+ | an_id ----------> id,name <-- analytic_code_id
+ |
+ |                   n_id    ---------------------> id,name
+
+The relationship between a model and a dimension is configured by *analytic structures*.
+Structure define how models point to dimensions and what analytic field to use.
+
+Example: You have a dimension ``D`` you wish to bind to model ``A``.
+You would create an ``analytic.structure`` record for ``A`` that references ``D`` through the ``Analysis 1`` slot.
+This would allow you to use the ``a1_id`` field (assuming the default prefix is used) to reference ``D`` records.
+
+Integrity of analytic codes
+---------------------------
+
+You cannot delete analytic codes that are referenced by objects.
+Moreover, you cannot delete objects that reference analytic codes that are referenced elsewhere.
+
+.. _ConfigureAnalyticFields:
+
 Configure your OpenERP server for analytic fields
 -------------------------------------------------
 
@@ -24,6 +82,8 @@
 
 
 
+.. _MetaAnalytic:
+
 Add the MetaAnalytic metaclass to a model
 -----------------------------------------
 
@@ -38,8 +98,8 @@
 
  __metaclass__ = MetaAnalytic
 
-
+.. _AnalyticFields:
 
 Add analytic fields to a model
 ------------------------------
 
@@ -42,8 +102,7 @@
 
 Add analytic fields to a model
 ------------------------------
 
-
 First of all, make sure you are using the MetaAnalytic metaclass.
 Then, add the _analytic attribute to your class, using the following syntax.
 
@@ -71,7 +130,6 @@
      't': 'account_move_line',
  }
 
-
 Add analytic fields to a view
 -----------------------------
 
@@ -109,6 +167,8 @@
 
 
 
+.. _AnalyticDimensions:
+
 Bind an analytic dimension to a model
 -------------------------------------