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

1 files changed, 74 insertions, 0 deletions

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