Issue 3618 - Add a script for generating the JSDoc documentation

generate_docs.py

 #!/usr/bin/env python
 # coding: utf-8
 
 import os
+import subprocess
 import sys
-import subprocess
 
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 DEPENDENCY_SCRIPT = os.path.join(BASE_DIR, "ensure_dependencies.py")
 
 if __name__ == "__main__":
   try:
     subprocess.check_call([sys.executable, DEPENDENCY_SCRIPT, BASE_DIR])
   except subprocess.CalledProcessError as e:
     print >>sys.stderr, e
     print >>sys.stderr, "Failed to ensure dependencies being up-to-date!"
 
   # We're faking an invocation of build.py here, because we would have to

[Felix Dahlke, 2016/02/03 10:59:55]

Yeah I know, it's hacky. But I'm not really convinced that it's worth
refactoring buildtools for right now. It's not really unlikely that we will want
to move the build logic for adblockpluscore into that repository at some point,
then we would have a build.py similar to what's in adblockplus and
adblockpluschrome.

   # duplicate command line parsing otherwise. It would be nicer if buildtools
   # would make it possible to invoke the docs command directly.
   args = sys.argv
   args[1:1] = ["-t", "gecko", "docs"]
 
   import buildtools.build
   buildtools.build.processArgs(BASE_DIR, args)

[Wladimir Palant, 2016/02/04 22:19:54]

As hacks go, I think this one is better:

  buildtools.build.generateDocs(BASE_DIR, os.path.basename(sys.argv[0]),
      {}, ['docs'], 'gecko')

[Felix Dahlke, 2016/02/05 06:17:54]

I went with that one at first, but then we have to duplicate command line
parsing and usage - I'd rather not. But if you prefer that, fine by me too.