Bug 1389341 - add basic support for sphinx-js to mach doc r=gps

MozReview-Commit-ID: FIzWD8tnjYi

--HG--
extra : rebase_source : 655ea46cffefda77f0908924fdbbb8d17212654a

build/sparse-profiles/sphinx-docs

@@ -7,6 +7,8 @@ glob:tools/docs/**
 # Potential docs sources
 glob:**/*.rst
 glob:**/*.md
+glob:**/*.js
+glob:**/*.jsm
 
 # Python API docs.
 glob:**/*.py

taskcluster/ci/source-test/doc.yml

@@ -25,6 +25,8 @@ generate:
             - '**/*.rst'
             - '**/*.md'
             - 'tools/docs/**'
+            - '**/*.js'
+            - '**/*.jsm'
 
 upload:
     description: Generate and upload the Sphinx documentation

taskcluster/docker/lint/system-setup.sh

@@ -49,6 +49,12 @@ cd /build
 
 . install-node.sh
 
+###
+# jsdoc Setup
+###
+
+npm install -g jsdoc@3.5.5
+
 /build/tooltool.py fetch -m /tmp/eslint.tt
 mv /build/node_modules /build/node_modules_eslint
 /build/tooltool.py fetch -m /tmp/eslint-plugin-mozilla.tt

tools/docs/conf.py

@@ -38,8 +38,15 @@ extensions = [
     'sphinx.ext.graphviz',
     'sphinx.ext.todo',
     'mozbuild.sphinx',
+    'sphinx_js',
 ]
 
+# JSDoc must run successfully for dirs specified, so running
+# tree-wide (the default) will not work currently.
+js_source_path = []
+root_for_relative_js_paths = '.'
+jsdoc_config_path = 'tools/docs/jsdoc.json'
+
 templates_path = ['_templates']
 source_suffix = '.rst'
 source_suffix = ['.rst', '.md']

tools/docs/jsdoc.json

@@ -0,0 +1,5 @@
+{
+  "source": {
+    "includePattern": ".+\\.jsm$"
+  }
+}

tools/docs/mach_commands.py

@@ -5,6 +5,7 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 import os
+import platform
 import sys
 
 from mach.decorators import (
@@ -13,6 +14,7 @@ from mach.decorators import (
     CommandProvider,
 )
 
+import which
 import mozhttpd
 
 from mozbuild.base import MachCommandBase
@@ -42,8 +44,14 @@ class Documentation(MachCommandBase):
                      help='Upload generated files to S3')
     def build_docs(self, what=None, format=None, outdir=None, auto_open=True,
                    http=None, archive=False, upload=False):
+        try:
+            jsdoc = which.which('jsdoc')
+        except which.WhichError:
+            return die('jsdoc not found - please install from npm.')
+
         self._activate_virtualenv()
-        self.virtualenv_manager.install_pip_package('sphinx_rtd_theme==0.1.6')
+        self.virtualenv_manager.install_pip_package('sphinx_rtd_theme==0.2.4')
+        self.virtualenv_manager.install_pip_package('sphinx-js==2.1')
         self.virtualenv_manager.install_pip_package('recommonmark==0.4.0')
 
         import sphinx
@@ -168,3 +176,4 @@ def die(msg, exit_code=1):
     msg = '%s: %s' % (sys.argv[0], msg)
     print(msg, file=sys.stderr)
     return exit_code
+