[NaCl SDK Docs] Simplify PPAPI documentation generation.

native_client_sdk/src/doc/doxygen/generate_docs.py

Index: native_client_sdk/src/doc/doxygen/generate_docs.py
diff --git a/native_client_sdk/src/doc/doxygen/generate_docs.py b/native_client_sdk/src/doc/doxygen/generate_docs.py
new file mode 100755
index 0000000000000000000000000000000000000000..560671acdf45cebf6b0111f68bee0fbf235f8dba
--- /dev/null
+++ b/native_client_sdk/src/doc/doxygen/generate_docs.py
@@ -0,0 +1,191 @@
+#!/usr/bin/python
+
+# Copyright (c) 2014 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+import json
+import optparse
+import os
+import shutil
+import subprocess
+import sys
+import urllib2
+
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+DOC_DIR = os.path.dirname(SCRIPT_DIR)
+
+
+def Trace(msg):
+  if Trace.verbose:
+    sys.stderr.write(str(msg) + '\n')
+
+Trace.verbose = False
+
+
+def GetChannelBranches():
+  url = 'http://omahaproxy.appspot.com/json'
+  u = urllib2.urlopen(url)
+  try:
+    data = json.loads(u.read())
+  finally:
+    u.close()
+
+  channel_branch = {}
+  for os_row in data:
+    os = os_row['os']
+    if os not in ('win', 'mac', 'linux'):
+      continue
+    for version_row in os_row['versions']:
+      channel = version_row['channel']
+      # We don't display canary docs.
+      if channel == 'canary':
+        continue
+
+      branch = version_row['true_branch']
+      if channel in channel_branch:
+        existing_branch = channel_branch[channel]
+        if branch != existing_branch:
+          sys.stderr.write('Warning: found different branch numbers for '
+              'channel %s: %s vs %s. Using %s.\n' % (
+              channel, branch, existing_branch, existing_branch))
+      else:
+        channel_branch[channel] = branch
+
+  return channel_branch
+
+
+def RemoveFile(filename):
+  try:
+    os.remove(filename)
+  except OSError:
+    pass

[Sam Clegg, 2014/01/15 23:22:59]

Why ignore these errors?

[binji, 2014/01/15 23:56:16]

I don't want to error when the file or directory doesn't exist. I guess in the
rest of the SDK we check via os.path.exists instead, right?

[binji, 2014/01/16 22:27:08]

Done.

+
+
+def RemoveDir(dirname):
+  try:
+    shutil.rmtree(dirname)
+  except OSError:
+    pass
+
+
+def CheckoutPepperDocs(branch, doc_dirname):
+  Trace('Removing directory %s' % doc_dirname)
+  RemoveDir(doc_dirname)
+
+  for subdir in ('c', 'cpp', 'utility'):
+    url = 'http://src.chromium.org/chrome/branches/%s/src/ppapi/%s' % (
+        branch, subdir)
+    cmd = ['svn', 'co', url, os.path.join(doc_dirname, subdir)]
+    Trace('Checking out docs into %s:\n  %s' % (doc_dirname, ' '.join(cmd)))
+    subprocess.check_call(cmd)
+
+
+def GenerateDoxyfile(template_filename, out_dirname, doc_dirname, doxyfile):
+  Trace('Writing Doxyfile "%s" (from template %s)' % (
+    doxyfile, template_filename))
+
+  with open(template_filename) as f:
+    data = f.read()
+
+  with open(doxyfile, 'w') as f:
+    f.write(data % {'out_dirname': out_dirname, 'doc_dirname': doc_dirname})
+
+
+def RunDoxygen(out_dirname, doxyfile):
+  Trace('Removing old output directory %s' % out_dirname)
+  RemoveDir(out_dirname)
+
+  Trace('Making new output directory %s' % out_dirname)
+  os.makedirs(out_dirname)
+
+  cmd = ['doxygen', doxyfile]
+  Trace('Running Doxygen:\n  %s' % ' '.join(cmd))
+  subprocess.check_call(cmd)
+
+
+def RunDoxyCleanup(out_dirname):
+  cmd = [sys.executable, 'doxy_cleanup.py', out_dirname]
+  if Trace.verbose:
+    cmd.append('-v')
+  Trace('Running doxy_cleanup:\n  %s' % ' '.join(cmd))
+  subprocess.check_call(cmd)
+
+
+def RunRstIndex(kind, channel, out_dirname, out_rst_filename):
+  assert kind in ('root', 'c', 'cpp')
+  cmd = [sys.executable, 'rst_index.py',
+         '--' + kind,
+         '--channel', channel,
+         out_dirname,
+         '-o', out_rst_filename]
+  Trace('Running rst_index:\n  %s' % ' '.join(cmd))
+  subprocess.check_call(cmd)
+
+
+def GenerateDocs(channel, branch):
+  Trace('Generating docs for %s (branch %s)' % (channel, branch))
+  pepper_dirname = 'pepper_%s' % channel
+  # i.e. ../_build/chromesite/pepper_beta
+  chromesite_dir = os.path.join(DOC_DIR, '_build', 'chromesite', pepper_dirname)
+
+  CheckoutPepperDocs(branch, pepper_dirname)
+
+  doxyfile_c = ''
+  doxyfile_cpp = ''
+
+  try:
+    # Generate Root index
+    rst_index_root = os.path.join(DOC_DIR, pepper_dirname, 'index.rst')
+    RunRstIndex('root', channel, chromesite_dir, rst_index_root)
+
+    # Generate C docs
+    out_dirname_c = os.path.join(chromesite_dir, 'c')
+    doxyfile_c = 'Doxyfile.c.%s' % channel
+    rst_index_c = os.path.join(DOC_DIR, pepper_dirname, 'c', 'index.rst')
+    GenerateDoxyfile('Doxyfile.c.template', out_dirname_c, pepper_dirname,
+                     doxyfile_c)
+    RunDoxygen(out_dirname_c, doxyfile_c)
+    RunDoxyCleanup(out_dirname_c)
+    RunRstIndex('c', channel, out_dirname_c, rst_index_c)
+
+    # Generate C++ docs
+    out_dirname_cpp = os.path.join(chromesite_dir, 'cpp')
+    doxyfile_cpp = 'Doxyfile.cpp.%s' % channel
+    rst_index_cpp = os.path.join(DOC_DIR, pepper_dirname, 'cpp', 'index.rst')
+    GenerateDoxyfile('Doxyfile.cpp.template', out_dirname_cpp, pepper_dirname,
+                     doxyfile_cpp)
+    RunDoxygen(out_dirname_cpp, doxyfile_cpp)
+    RunDoxyCleanup(out_dirname_cpp)
+    RunRstIndex('cpp', channel, out_dirname_cpp, rst_index_cpp)
+  finally:
+    # Cleanup
+    RemoveDir(pepper_dirname)
+    RemoveFile(doxyfile_c)
+    RemoveFile(doxyfile_cpp)
+
+
+def main(argv):
+  parser = optparse.OptionParser(usage='Usage: %prog [options]')
+  parser.add_option('-v', '--verbose',
+                    help='Verbose output', action='store_true')
+  options, files = parser.parse_args(argv)
+
+  if options.verbose:
+    Trace.verbose = True
+
+  channel_branch = GetChannelBranches()
+  for channel, branch in channel_branch.iteritems():
+    GenerateDocs(channel, branch)
+
+  return 0
+
+
+if __name__ == '__main__':
+  try:
+    rtn = main(sys.argv[1:])
+  except KeyboardInterrupt:
+    sys.stderr.write('%s: interrupted\n' % os.path.basename(__file__))
+    rtn = 1
+  sys.exit(rtn)