Issue 2271 - Enable documentation for Chrome extensions

build.py

 # coding: utf-8
 
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 import os, sys, re, subprocess, shutil, buildtools
 from getopt import getopt, GetoptError
 from StringIO import StringIO
 from zipfile import ZipFile
@@ skipping 351 matching lines @@
       )).encode('utf-8')
 
 
 def generateDocs(baseDir, scriptName, opts, args, type):
   if len(args) == 0:
     print 'No target directory specified for the documentation'
     usage(scriptName, type, 'docs')
     return
   targetDir = args[0]
 
-  command = ['jsdoc',
-             '--destination', targetDir,
-             '--access', 'all',
-             os.path.join(baseDir, 'lib')]
+  source_dir = os.path.join(baseDir, 'lib')
+  sources = [source_dir]
+
+  # JSDoc struggles wih huge objects: https://github.com/jsdoc3/jsdoc/issues/976

[kzar, 2015/04/05 12:51:41]

Maybe instead of this logic we could use a JSdoc configuration file with an
exclude pattern? http://usejsdoc.org/about-configuring-jsdoc.html

[Sebastian Noack, 2015/04/05 13:08:56]

This would be kinda nice, because the JSDoc configuration could be done in the
repective repo then, and the logic in buildtools could be agnostic of the source
files.

But on the other hand this hack will (hopefully) be just temporarily. And the
logic is simpler without delegating to a config file.

[kzar, 2015/04/05 13:30:51]

Wouldn't the logic be pretty simple if we use a config file though? I thought we
could just add an extra argument to the command array to specify the config
path, and then just use the configuration for special things like excluding
publicSuffixList.js. Otherwise avoiding changes to this chunk of code.

[Sebastian Noack, 2015/04/05 13:34:33]

The logic here would be reasonable. But the actual logic is just delegated to
the configfile. And spreading logic isn't great, unless there is a reason for
it.

[kzar, 2015/04/05 15:12:55]

Fair enough I suppose.

+  if type == 'chrome':
+    sources = [os.path.join(source_dir, filename) for filename in os.listdir(source_dir) if filename != 'publicSuffixList.js']
+
+  command = ['jsdoc', '--destination', targetDir, '--access', 'all'] + sources
   if any(opt in ('-q', '--quiet') for opt, _ in opts):
     process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
     stderr = process.communicate()[1]
     retcode = process.poll()
     if retcode:
       sys.stderr.write(stderr)
       raise subprocess.CalledProcessError(command, retcode)
   else:
     subprocess.check_call(command)
 
@@ skipping 90 matching lines @@
   command.description = 'Display description strings for all locales as specified in the corresponding meta.properties files.'
   command.addOption('Only include the given locales', short='l', long='locales', value='l1,l2,l3')
   command.params = '[options]'
   command.supportedTypes = ('gecko')
 
 with addCommand(generateDocs, 'docs') as command:
   command.shortDescription = 'Generate documentation (requires node.js)'
   command.description = 'Generate documentation files and write them into the specified directory. This operation requires JsDoc 3 to be installed.'
   command.addOption('Suppress JsDoc output', short='q', long='quiet')
   command.params = '[options] <directory>'
-  command.supportedTypes = ('gecko')
+  command.supportedTypes = ('gecko', 'chrome')
 
 with addCommand(runReleaseAutomation, 'release') as command:
   command.shortDescription = 'Run release automation'
   command.description = 'Note: If you are not the project owner then you '\
     'probably don\'t want to run this!\n\n'\
     'Runs release automation: creates downloads for the new version, tags '\
     'source code repository as well as downloads and buildtools repository.'
   command.addOption('File containing private key and certificates required to sign the release. Note that for Chrome releases this option needs to be specified twice: first a key to sign Chrome/Opera builds, then another to sign the Safari build.', short='k', long='key', value='file', types=('gecko', 'chrome'))
   command.addOption('Directory containing downloads repository (if omitted ../downloads is assumed)', short='d', long='downloads', value='dir')
   command.params = '[options] <version>'
@@ skipping 68 matching lines @@
         if option in ('-h', '--help'):
           usage(scriptName, type, command)
           sys.exit()
       commands[command](baseDir, scriptName, opts, args, type)
     else:
       print 'Command %s is not supported for this application type' % command
       usage(scriptName, type)
   else:
     print 'Command %s is unrecognized' % command
     usage(scriptName, type)