[ADD] doc: JS document extraction system

* Fix a bunch of ill-documented/incomplete/incorrect method docs
* add start of Sphinx extension to extract & integrate jsdoc into
  Sphinx documentation:

  - parse JS files (and don't blow up), uses a fork of pyjsparser as
    the project currently does not parse comments
  - extract cross-module dependency information
  - parse JsDoc comments using pyjsdoc and infer structure from code &
    jsdoc
  - ``ast`` CLI printing a simplified AST of the input files
  - ``dependencies`` creating a dependency graph of either all modules
    in the provided input files or the modules matching the specified
    filters (warning: will not work if missing dependencies),
    generates a .dot file
  - ``extractor`` generating a plain text module documentation (mix of
    rst and markdown styles, not anything formal)
* sphinx extension with an "automodule" directive taking a module name
  and generating the documentation for it

1 files changed, 75 insertions, 0 deletions

diff --git a/doc/_extensions/autojsdoc/parser/tests/test_crap.py b/doc/_extensions/autojsdoc/parser/tests/test_crap.py
new file mode 100644
index 00000000000..70063e6dd47
--- /dev/null
+++ b/doc/_extensions/autojsdoc/parser/tests/test_crap.py
@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""
+Test various crap patterns found in Odoo code to ensure they don't blow up
+the parser thingie
+"""
+from autojsdoc.parser import jsdoc
+from support import parse
+
+def test_export_external():
+    [mod] = parse("""
+    odoo.define('module', function () {
+        return $.Deferred().reject();
+    });
+    """)
+    assert isinstance(mod.exports, jsdoc.CommentDoc)
+    assert mod.exports.doc == ''
+
+def test_extend_jq():
+    parse("""
+    odoo.define('a', function (r) {
+        $.extend($.expr[':'], { a: function () {} });
+        $.fn.extend({ a: function () {} });
+    });
+    """)
+
+def test_extend_dynamic():
+    parse("""
+    odoo.define('a', function () {
+        foo.bar.baz[qux + '_external'] = function () {};
+    });
+    """)
+
+def test_extend_deep():
+    parse("""
+    odoo.define('a', function () {
+        var eventHandler = $.summernote.eventHandler;
+        var dom = $.summernote.core.dom;
+        dom.thing = function () {};
+
+        var fn_editor_currentstyle = eventHandler.modules.editor.currentStyle;
+        eventHandler.modules.editor.currentStyle = function () {}
+    });
+    """)
+
+def test_arbitrary():
+    parse("""
+    odoo.define('bob', function () {
+        var page = window.location.href.replace(/^.*\/\/[^\/]+/, '');
+        var mailWidgets = ['mail_followers', 'mail_thread', 'mail_activity', 'kanban_activity'];
+        var bob;
+        var fldj = foo.getTemplate().baz;
+    });
+    """)
+
+def test_prototype():
+    [A, B] = parse("""
+    odoo.define('mod1', function () {
+        var exports = {};
+        exports.Foo = Backbone.Model.extend({});
+        exports.Bar = Backbone.Model.extend({});
+        var BarCollection = Backbone.Collection.extend({
+            model: exports.Bar,
+        });
+        exports.Baz = Backbone.Model.extend({});
+        return exports;
+    });
+    odoo.define('mod2', function (require) {
+        var models = require('mod1');
+        var _super_orderline = models.Bar.prototype;
+        models.Foo = models.Bar.extend({});
+        var _super_order = models.Baz.prototype;
+        models.Bar = models.Baz.extend({});
+    });
+    """)
+