[telemetry] Initial (autogenerated) documentation plus support scripts

tools/telemetry/build/update_docs.py

+# Copyright (c) 2012 The Chromium Authors. All rights reserved.

[tonyg, 2013/06/18 16:09:11]

nit: 2013

+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+import logging
+import optparse
+import os
+import sys

[tonyg, 2013/06/18 16:09:11]

nit: alphabetize

+import pkgutil
+import pydoc
+
+def UnlinkAllDocs(docs_dir):

[tonyg, 2013/06/18 16:09:11]

Can we name this RemoveAllDocs and call os.remove instead. They are the same
function, but I think the term remove is more widely understood (I had to look
up unlink assuming it had something to do with symbolic links).

+  for dirname, _, filenames in os.walk(docs_dir):
+    for filename in filenames:
+      os.unlink(os.path.join(dirname, filename))
+
+def WriteDocsFor(module):
+  pydoc.writedoc(module)
+  for _, modname, _ in pkgutil.walk_packages(
+      module.__path__, module.__name__ + '.'):
+    if modname.endswith('_unittest'):
+      logging.info("skipping %s due to being a unittest", modname)
+      continue
+
+    module = __import__(modname, fromlist=[""])
+    name, _ = os.path.splitext(module.__file__)
+    if not os.path.exists(name + '.py'):
+      logging.info("skipping %s due to being an orphan .pyc", module.__file__)
+      continue
+
+    pydoc.writedoc(module)
+
+def Main(args):
+  parser = optparse.OptionParser()
+  parser.add_option(
+      '-v', '--verbose', action='count', default=0,
+      help='Increase verbosity level (repeat as needed)')
+  options, args = parser.parse_args(args)
+  if options.verbose >= 2:
+    logging.basicConfig(level=logging.DEBUG)
+  elif options.verbose:
+    logging.basicConfig(level=logging.INFO)
+  else:
+    logging.basicConfig(level=logging.WARNING)
+
+  toplevel_dir = os.path.abspath(
+    os.path.join(
+      os.path.dirname(__file__), '..'))

[tonyg, 2013/06/18 16:09:11]

util.GetTelemetryDir() ?

+  docs_dir = os.path.join(toplevel_dir, 'docs')
+
+  assert os.path.isdir(docs_dir)
+  assert os.path.exists(
+    os.path.join(toplevel_dir,
+                 'telemetry', '__init__.py'))
+
+  UnlinkAllDocs(docs_dir)
+
+  if toplevel_dir not in sys.path:
+    sys.path.append(toplevel_dir)
+  import telemetry
+
+  old_cwd = os.getcwd()
+  try:
+    os.chdir(docs_dir)
+    WriteDocsFor(telemetry)
+  finally:
+    os.chdir(old_cwd)