[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, 116 insertions, 0 deletions

diff --git a/doc/_extensions/autojsdoc/parser/tests/test_params.py b/doc/_extensions/autojsdoc/parser/tests/test_params.py
new file mode 100644
index 00000000000..c51139b8cb3
--- /dev/null
+++ b/doc/_extensions/autojsdoc/parser/tests/test_params.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+from autojsdoc.parser.jsdoc import ParamDoc
+
+"Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+
+def test_basic():
+    d = ParamDoc("Lorem ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': 'Lorem',
+        'type': '',
+        'optional': False,
+        'default': None,
+        'doc': 'ipsum dolor sit amet, consectetur adipiscing elit.',
+    }
+
+    d = ParamDoc("{Lorem} ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': 'ipsum',
+        'type': 'Lorem',
+        'optional': False,
+        'default': None,
+        'doc': 'dolor sit amet, consectetur adipiscing elit.',
+    }
+
+def test_optional():
+    d = ParamDoc("[Lorem] ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': 'Lorem',
+        'type': '',
+        'optional': True,
+        'default': None,
+        'doc': 'ipsum dolor sit amet, consectetur adipiscing elit.',
+    }
+
+    d = ParamDoc("[Lorem=42] ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': 'Lorem',
+        'type': '',
+        'optional': True,
+        'default': "42",
+        'doc': 'ipsum dolor sit amet, consectetur adipiscing elit.',
+    }
+
+    d = ParamDoc("{Lorem} [ipsum] dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': 'ipsum',
+        'type': 'Lorem',
+        'optional': True,
+        'default': None,
+        'doc': 'dolor sit amet, consectetur adipiscing elit.',
+    }
+
+    d = ParamDoc("{Lorem} [ipsum=42] dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': 'ipsum',
+        'type': 'Lorem',
+        'optional': True,
+        'default': '42',
+        'doc': 'dolor sit amet, consectetur adipiscing elit.',
+    }
+
+def test_returns():
+    d = ParamDoc("{}  ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': '',
+        'type': '',
+        'optional': False,
+        'default': None,
+        'doc': 'ipsum dolor sit amet, consectetur adipiscing elit.',
+    }
+    d = ParamDoc("{Lorem}  ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d == {
+        'name': '',
+        'type': 'Lorem',
+        'optional': False,
+        'default': None,
+        'doc': 'ipsum dolor sit amet, consectetur adipiscing elit.',
+    }
+
+def test_odd():
+    d = ParamDoc("{jQuery} [$target] the node where content will be prepended").to_dict()
+    assert d == {
+        'name': '$target',
+        'type': 'jQuery',
+        'optional': True,
+        'default': None,
+        'doc': 'the node where content will be prepended',
+    }
+
+    d = ParamDoc("""{htmlString} [content] DOM element,
+  array of elements, HTML string or jQuery object to prepend to $target""").to_dict()
+    assert d == {
+        'name': 'content',
+        'type': 'htmlString',
+        'optional': True,
+        'default': None,
+        'doc': "DOM element,\n  array of elements, HTML string or jQuery object to prepend to $target",
+    }
+
+    d = ParamDoc("{Boolean} [options.in_DOM] true if $target is in the DOM").to_dict()
+    assert d == {
+        'name': 'options.in_DOM',
+        'type': 'Boolean',
+        'optional': True,
+        'default': None,
+        'doc': 'true if $target is in the DOM',
+    }
+
+    d = ParamDoc("Lorem\n   ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d['doc'] == 'ipsum dolor sit amet, consectetur adipiscing elit.'
+
+    d = ParamDoc("Lorem - ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d['doc'] == 'ipsum dolor sit amet, consectetur adipiscing elit.'
+
+    d = ParamDoc("Lorem : ipsum dolor sit amet, consectetur adipiscing elit.").to_dict()
+    assert d['doc'] == 'ipsum dolor sit amet, consectetur adipiscing elit.'