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

diff --git a/doc/_extensions/autojsdoc/parser/tests/support.py b/doc/_extensions/autojsdoc/parser/tests/support.py
new file mode 100644
index 00000000000..f533f98d90c
--- /dev/null
+++ b/doc/_extensions/autojsdoc/parser/tests/support.py
@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+import operator
+
+import pyjsparser
+
+from autojsdoc.parser import jsdoc, parser
+
+params = operator.attrgetter('name', 'type', 'doc')
+
+
+def parse(s, source=None):
+    tree = pyjsparser.parse(s)
+    mods = parser.ModuleMatcher(source).visit(tree)
+    post(mods)
+    return mods
+
+def post(mods):
+    modules = dict(BASE_MODULES)
+    modules.update((m.name, m) for m in mods)
+
+    for mod in mods:
+        mod.post_process(modules)
+
+BASE_MODULES = {
+    'other': jsdoc.ModuleDoc({
+        'module': 'other',
+        '_members': [
+            ('<exports>', jsdoc.LiteralDoc({'name': 'value', 'value': "ok"})),
+        ],
+    }),
+    'dep2': jsdoc.ModuleDoc({
+        'module': 'dep2',
+        '_members': [
+            ('<exports>', jsdoc.LiteralDoc({'value': 42.})),
+        ],
+    }),
+    'dep3': jsdoc.ModuleDoc({
+        'module': 'dep3',
+        '_members': [
+            ('<exports>', jsdoc.LiteralDoc({'value': 56.})),
+        ],
+    }),
+    'Class': jsdoc.ModuleDoc({
+        'module': 'Class',
+        '_members': [
+            ('<exports>', jsdoc.ClassDoc({
+                'name': 'Class',
+                'doc': "Base Class"
+            })),
+        ],
+    }),
+    'mixins': jsdoc.ModuleDoc({
+        'module': 'mixins',
+        '_members': [
+            ('<exports>', jsdoc.NSDoc({
+                'name': 'mixins',
+                '_members': [
+                    ('Bob', jsdoc.ClassDoc({'class': "Bob"})),
+                ]
+            })),
+        ],
+    }),
+    'Mixin': jsdoc.ModuleDoc({
+        'module': 'Mixin',
+        '_members': [
+            ('<exports>', jsdoc.MixinDoc({
+                '_members': [
+                    ('a', jsdoc.FunctionDoc({'function': 'a'})),
+                ]
+            })),
+        ],
+    })
+}