[FIX] doc building and warnings

doc:

* fix incorrect doc comments (documenting params which don't exist)
* correctly quote non-refs
* fix role label syntax (backticks must be escaped)
* add newline to fix warning

JS doc parser:

* fix handling of already-resolved objects
* fix handling of non-string properties (e.g. foo[0] at module toplevel)
* don't blow up if subject of .include call can't be resolved (just ignore)

Others:

* add translator support for ``problematic`` node (apparently used for
  some refs by recent Sphinx)

addons/mail/static/src/js/models/threads/mailbox.js

@@ -20,10 +20,8 @@ var Mailbox = SearchableThread.extend({
      * @override
      * @param {Object} params
      * @param {Object} params.data
-     * @param {string} params.data.id the ID of the mailbox, without the
-     *   'mailbox_' prefix.
-     * @param {integer} [params.data.mailboxCounter=0] the initial mailbox
-     *   counter of this mailbox.
+     * @param {string} params.data.id the ID of the mailbox, without the ``mailbox_`` prefix.
+     * @param {integer} [params.data.mailboxCounter=0] the initial mailbox counter of this mailbox.
      */
     init: function (params) {
         var data = params.data;

addons/web/static/src/js/core/dom.js

@@ -438,7 +438,7 @@ return {
         }
     },
     /**
-     * Cleans what has been done by `initAutoMoreMenu'.
+     * Cleans what has been done by ``initAutoMoreMenu``.
      *
      * @param {jQuery} $el
      */

addons/web/static/src/js/core/domain.js

@@ -458,7 +458,7 @@ var Domain = collections.Tree.extend({
      * Converts python condition to a JS prefix-array representation of a domain
      *
      * @static
-     * @param {string} domain
+     * @param {string} condition
      * @returns {Array}
      */
     conditionToDomain: function (condition) {

addons/web/static/src/js/views/search/filters_menu.js

@@ -47,9 +47,7 @@ var FiltersMenu = DropdownMenu.extend({
      *      defaultOptionId: string refers to an optionId (optional)
      *      currentOptionId: string refers to an optionId that is activated if item is active (optional)
      *   }
-     * @param {Object[]} periodOptions determines the options available for filter with date attribute
-     * @param {Object} fields 'field_get' of a model: mapping from field name
-     * to an object with its properties
+     * @param {Object} fields
      */
     init: function (parent, filters, fields) {
         // determines where the filter menu is displayed and its style

doc/_extensions/autojsdoc/parser/jsdoc.py

@@ -62,6 +62,11 @@ class CommentDoc(pyjsdoc.CommentDoc):
         d['name'] = self.name
         return d
 
+    # don't resolve already resolved docs (e.g. a literal dict being
+    # include-ed in two different classes because I don't even care anymore
+    def become(self, modules):
+        return self
+
 class PropertyDoc(CommentDoc):
     @classmethod
     def from_param(cls, s, sourcemodule=None):

doc/_extensions/autojsdoc/parser/parser.py

@@ -60,7 +60,7 @@ ref = collections.namedtuple('Ref', 'object property')
 def _name(r):
     bits = []
     while isinstance(r, ref):
-        bits.append(r.property)
+        bits.append(str(r.property))
         r = r.object
     return '.'.join(reversed(bits))
 def deref(item, prop=None):
@@ -348,7 +348,8 @@ class ModuleExtractor(Visitor):
             def resolve_extension(modules):
                 t = target.become(modules)
                 if not isinstance(t, jsdoc.ClassDoc):
-                    raise ValueError("include() subjects should be classes, %s is %s" % (target_name, type(t)))
+                    return # FIXME: log warning
+                    # raise ValueError("include() subjects should be classes, %s is %s" % (target_name, type(t)))
                 # TODO: note which module added these
                 for it in items:
                     if isinstance(it, dict):

doc/_extensions/odoo_ext/translator.py

@@ -190,6 +190,18 @@ class BootstrapTranslator(nodes.NodeVisitor, object):
     def depart_compact_paragraph(self, node):
         pass
 
+    def visit_problematic(self, node):
+        if node.hasattr('refid'):
+            self.body.append('<a href="#%s">' % node['refid'])
+            self.context.append('</a>')
+        else:
+            self.context.append('')
+        self.body.append(self.starttag(node, 'span', CLASS='problematic'))
+
+    def depart_problematic(self, node):
+        self.body.append('</span>')
+        self.body.append(self.context.pop())
+
     def visit_literal_block(self, node):
         if node.rawsource != node.astext():
             # most probably a parsed-literal block -- don't highlight

doc/reference/orm.rst

@@ -288,7 +288,7 @@ Common ORM methods
         >>> self.create([{'name': "Jack"}, {'name': "William"}, {'name': "Averell"}])
         res.partner(79, 80, 81)
 
-    See :ref:`how to define method `create` with one API or the other
+    See :ref:`how to define method \`create\` with one API or the other
     <reference/orm/oldapi>`.
 
 :meth:`~odoo.models.Model.write`

doc/setup/enterprise.rst

@@ -1,4 +1,5 @@
 :banner: banners/enterprise.jpg
+
 .. _setup/enterprise:
 
 ============================