From 4e784adbf7ecac4b4f2c86b286c51de52a448604 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@odoo.com>
Date: Thu, 5 Apr 2018 12:26:27 +0200
Subject: [PATCH] [FIX] doc: non-module JS autodocumenters

Also when there is both a docstring and directive-level content put
the docstring first. That seems to match what Sphinx's autodoc does
and looks less odd.

Possible future improvement: a parameter to suppress the docstring?
Possibly a way to reorder the non-docstring content (e.g. members
documentation)?
---
 doc/_extensions/autojsdoc/ext/directives.py | 40 +++++++++++++++++----
 doc/reference/javascript_reference.rst      | 20 +++++------
 2 files changed, 42 insertions(+), 18 deletions(-)

diff --git a/doc/_extensions/autojsdoc/ext/directives.py b/doc/_extensions/autojsdoc/ext/directives.py
index d127e24725b..649de9d151c 100644
--- a/doc/_extensions/autojsdoc/ext/directives.py
+++ b/doc/_extensions/autojsdoc/ext/directives.py
@@ -115,13 +115,24 @@ def autodirective_bound(app, modules):
         def run(self):
             self.env = self.state.document.settings.env
 
-            # strip 'js:auto'
             objname = self.arguments[0].strip()
+            if not modules:
+                read_js(app, modules)
 
-            path = self.env.temp_data.get('autojs:prefix', []) + [objname]
-            item = modules[path[0]]
+            # build complete path to object
+            path = self.env.temp_data.get('autojs:prefix', []) + objname.split('.')
+            # look for module/object split
+            for i in range(1, len(path)):
+                modname, objpath = '.'.join(path[:-i]), path[-i:]
+                module = modules.get(modname)
+                if module:
+                    break
+            else:
+                raise Exception("Found no valid module in " + '.'.join(path))
+
+            item = module
             # deref' namespaces until we reach the object we're looking for
-            for k in path[1:]:
+            for k in objpath:
                 item = item.get_property(k)
 
             docclass = documenters[self.name]
@@ -210,8 +221,12 @@ class NSDocumenter(Documenter):
     def make_content(self, all_members):
         doc = self.item
         ret = nodes.section()
+
         if doc.doc:
             self.directive.state.nested_parse(to_list(doc.doc), 0, ret)
+
+        self.directive.state.nested_parse(self.directive.content, 0, ret)
+
         ret += self.document_properties(all_members)
         return ret.children
 
@@ -307,12 +322,12 @@ class ModuleDocumenter(NSDocumenter):
                     with addto(fields, nodes.field()) as field:
                         self.make_dependencies(field, doc)
 
-        self.directive.state.nested_parse(self.directive.content, 0, content)
-
         if doc.doc:
             # FIXME: source offset
             self.directive.state.nested_parse(to_list(doc.doc, source=doc['sourcefile']), 0, content)
 
+        self.directive.state.nested_parse(self.directive.content, 0, content)
+
         content += self.document_properties(all_members)
 
         return content
@@ -395,6 +410,8 @@ class ClassDocumenter(NSDocumenter):
         if doc.doc:
             self.directive.state.nested_parse(to_list(doc.doc), 0, ret)
 
+        self.directive.state.nested_parse(self.directive.content, 0, ret)
+
         ret += self.document_properties(all_members)
 
         ret += self.document_subtypes(subtypes)
@@ -466,9 +483,12 @@ class InstanceDocumenter(Documenter):
 
     def make_content(self, all_members):
         ret = nodes.section()
+
         if self.item.doc:
             self.directive.state.nested_parse(to_list(self.item.doc), 0, ret)
-            return ret.children
+
+        self.directive.state.nested_parse(self.directive.content, 0, ret)
+
         return ret.children
 
 class FunctionDocumenter(Documenter):
@@ -487,9 +507,12 @@ class FunctionDocumenter(Documenter):
     def make_content(self, all_members):
         ret = nodes.section()
         doc = self.item
+
         if doc.doc:
             self.directive.state.nested_parse(to_list(doc.doc), 0, ret)
 
+        self.directive.state.nested_parse(self.directive.content, 0, ret)
+
         check_parameters(self, doc)
 
         params, subtypes = extract_subtypes(self.item.name, self.item)
@@ -677,6 +700,9 @@ class PropertyDocumenter(Documenter):
     def make_content(self, all_members):
         doc = self.item
         ret = nodes.section()
+
+        self.directive.state.nested_parse(self.directive.content, 0, ret)
+
         if doc.doc:
             self.directive.state.nested_parse(to_list(doc.doc), 0, ret)
         return ret.children
diff --git a/doc/reference/javascript_reference.rst b/doc/reference/javascript_reference.rst
index f27975742fe..b77aa9f5612 100644
--- a/doc/reference/javascript_reference.rst
+++ b/doc/reference/javascript_reference.rst
@@ -1,5 +1,9 @@
 :banner: banners/javascript.jpg
 
+.. highlight:: javascript
+
+.. default-domain:: js
+
 =====================
 Javascript Reference
 =====================
@@ -1644,19 +1648,13 @@ order.
 Relational fields
 -----------------
 
-- selection (FieldSelection)
-    The FieldSelection widget is a simple select tag with a dropdown menu to
-    allow the selection of a range of values.  It is designed to work with fields
-    of type 'selection' and 'many2one'. When working with a many2one, it does
-    not allow the creation/edition of relational data.  This is the default field
-    for selection fields.
+.. autoclass:: web.relational_fields.FieldSelection
 
-    - Supported field types: *selection, many2one*
+    Supported field types: *selection*, *many2one*
 
-    Attributes:
+    .. attribute:: placeholder
 
-    - placeholder: a string which is used to display some info when no value is
-      selected
+        a string which is used to display some info when no value is selected
 
     .. code-block:: xml
 
@@ -1816,4 +1814,4 @@ Relational fields
 .. _event delegation:
     http://api.jquery.com/delegate/
 
-.. _deferred: http://api.jquery.com/category/deferred-object/
\ No newline at end of file
+.. _deferred: http://api.jquery.com/category/deferred-object/