[IMP] doc: guidelines references + minor corrections

X-original-commit: c83e999c6a8b16f78dfd9f944936439a53d2b52f

1 files changed, 45 insertions, 29 deletions

diff --git a/doc/reference/guidelines.rst b/doc/reference/guidelines.rst
index 367a30ddad8..2b6dc4a0a23 100644
--- a/doc/reference/guidelines.rst
+++ b/doc/reference/guidelines.rst
@@ -2,6 +2,8 @@
 
 .. highlight:: python
 
+.. _reference/guidelines:
+
 ===============
 Odoo Guidelines
 ===============
@@ -53,8 +55,8 @@ File naming
 
 File naming is important to quickly find information through all odoo addons.
 This section explains how to name files in a standard odoo module. As an
-example we use a plant nursery application. It holds two main models plant.nursery
-and plant.order.
+example we use a `plant nursery <https://github.com/tivisse/odoodays-2018/tree/master/plant_nursery>`_ application.
+It holds two main models *plant.nursery* and *plant.order*.
 
 Concerning *models*, split the business logic by sets of models belonging to
 a same main model. Each set lies in a given file named based on its main model.
@@ -236,6 +238,8 @@ The complete tree of our Odoo module therefore looks like
 
 .. warning:: Use correct file permissions : folder 755 and file 644.
 
+.. _reference/guidelines/xml:
+
 XML files
 =========
 
@@ -387,6 +391,8 @@ based upon the first one.
         ...
     </record>
 
+.. _reference/guidelines/python:
+
 Python
 ======
 
@@ -417,18 +423,16 @@ Inside these 3 groups, the imported lines are alphabetically sorted.
     import re
     import time
     from datetime import datetime
-    # 2 :  imports of odoo
+    # 2 : imports of odoo
     import odoo
-    from odoo import api, fields, models # alphabetically ordered
+    from odoo import api, fields, models, _ # alphabetically ordered
     from odoo.tools.safe_eval import safe_eval as eval
-    from odoo.tools.translate import _
-    # 3 :  imports from odoo addons
+    # 3 : imports from odoo addons
     from odoo.addons.website.models.website import slug
     from odoo.addons.web.controllers.main import login_redirect
 
-
-Idiomatics Python Programming
------------------------------
+Idiomatics of Programming (Python)
+----------------------------------
 
 - Each python file should have ``# -*- coding: utf-8 -*-`` as first line.
 - Always favor *readability* over *conciseness* or using the language features or idioms.
@@ -619,12 +623,14 @@ a different context, the ``with_context`` method should be used :
     records.with_context(new_context).do_stuff() # all the context is replaced
     records.with_context(**additionnal_context).do_other_stuff() # additionnal_context values override native context ones
 
-Passing parameter in context can have dangerous side-effects. Since the values
-are propagated automatically, some behavior can appears. Calling ``create()``
-method of a model with *default_my_field* key in context will set the default
-value of *my_field* for the concerned model. But if curing this creation, other
-object (such as sale.order.line, on sale.order creation) having a field
-name *my_field*, their default value will be set too.
+.. warning::
+      Passing parameter in context can have dangerous side-effects.
+
+      Since the values are propagated automatically, some unexpected behavior may appear.
+      Calling ``create()`` method of a model with *default_my_field* key in context
+      will set the default value of *my_field* for the concerned model.
+      But if during this creation, other objects (such as sale.order.line, on sale.order creation)
+      having a field name *my_field* are created, their default value will be set too.
 
 If you need to create a key context influencing the behavior of some object,
 choice a good name, and eventually prefix it by the name of the module to
@@ -701,6 +707,7 @@ online documentation of pyscopg2 to learn of to use it properly:
 
 Think extendable
 ~~~~~~~~~~~~~~~~
+
 Functions and methods should not contain too much logic: having a lot of small
 and simple methods is more advisable than having few large and complex methods.
 A good rule of thumb is to split a method as soon as it has more than one
@@ -820,7 +827,7 @@ importing as follows:
 
 .. code-block:: python
 
-    from odoo.tools.translate import _
+    from odoo import _
 
 A few very important rules must be followed when using it, in order for it to
 work and to avoid filling the translations with useless junk.
@@ -1002,6 +1009,7 @@ Symbols and Conventions
         def mail_user_confirm(self):
             ...
 
+.. _reference/guidelines/js:
 
 Javascript and CSS
 ==================
@@ -1020,18 +1028,24 @@ statically available at the url *your-odoo-server.com/web/static/src/js/some_fil
 The convention is to organize the code according to the following structure:
 
 - *static*: all static files in general
-- *static/lib*: this is the place where js libs should be located, in a sub folder.
-  So, for example, all files from the *jquery* library are in *addons/web/static/lib/jquery*
-- *static/src*: the generic static source code folder
-- *static/src/css*: all css files
-- *static/src/fonts*
-- *static/src/img*
-- *static/src/js*
-- *static/src/js/tours*: end user tour files (tutorials, not tests)
-- *static/src/scss*: scss files
-- *static/src/xml*: all qweb templates that will be rendered in JS
-- *static/tests*: this is where we put all test related files (QUnit).
-- *static/tests/tours*: this is where we put all tour test files (not tutorials).
+
+  - *static/lib*: this is the place where js libs should be located, in a sub folder.
+    So, for example, all files from the *jquery* library are in *addons/web/static/lib/jquery*
+  - *static/src*: the generic static source code folder
+
+    - *static/src/css*: all css files
+    - *static/src/fonts*
+    - *static/src/img*
+    - *static/src/js*
+
+      - *static/src/js/tours*: end user tour files (tutorials, not tests)
+      
+    - *static/src/scss*: scss files
+    - *static/src/xml*: all qweb templates that will be rendered in JS
+
+  - *static/tests*: this is where we put all test related files.
+
+    - *static/tests/tours*: this is where we put all tour test files (not tutorials).
 
 Javascript coding guidelines
 ----------------------------
@@ -1041,7 +1055,7 @@ Javascript coding guidelines
 - Never add minified Javascript Libraries
 - Use camelcase for class declaration
 
-More precise JS guidelines are detailed at https://github.com/odoo/odoo/wiki/Javascript-coding-guidelines.
+More precise JS guidelines are detailed in the `github wiki  <https://github.com/odoo/odoo/wiki/Javascript-coding-guidelines>`_.
 You may also have a look at existing API in Javascript by looking Javascript
 References.
 
@@ -1057,6 +1071,8 @@ CSS coding guidelines
 - Use Bootstrap native classes
 - Use underscore lowercase notation to name class
 
+.. _reference/guidelines/git:
+
 Git
 ===