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

5 files changed, 22 insertions, 3 deletions

diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py
index ff6d3196254..eb9d595330a 100644
--- a/doc/_extensions/autojsdoc/parser/jsdoc.py
+++ b/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):
diff --git a/doc/_extensions/autojsdoc/parser/parser.py b/doc/_extensions/autojsdoc/parser/parser.py
index d979170bbc9..a5eb45a8e85 100644
--- a/doc/_extensions/autojsdoc/parser/parser.py
+++ b/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):
diff --git a/doc/_extensions/odoo_ext/translator.py b/doc/_extensions/odoo_ext/translator.py
index da4e8731628..cf6c149d063 100644
--- a/doc/_extensions/odoo_ext/translator.py
+++ b/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
diff --git a/doc/reference/orm.rst b/doc/reference/orm.rst
index a7febdc7c7b..14dfdb4c058 100644
--- a/doc/reference/orm.rst
+++ b/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`
diff --git a/doc/setup/enterprise.rst b/doc/setup/enterprise.rst
index 66f8fe82671..0051b1fafc1 100644
--- a/doc/setup/enterprise.rst
+++ b/doc/setup/enterprise.rst
@@ -1,4 +1,5 @@
 :banner: banners/enterprise.jpg
+
 .. _setup/enterprise:
 
 ============================