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

1 files changed, 33 insertions, 7 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