Basic setup for generating app docs

chrome/common/extensions/docs/build/build.py

 #!/usr/bin/python
 # Copyright (c) 2012 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.
 
 """Docbuilder for extension docs."""
 
 import glob
 import os
 import os.path
@@ skipping 30 matching lines @@
 # the calling environment may not be setup to set the PYTHONPATH
 # Insert at the front so that we pick up our simplejson even if there's a
 # system simplejson installed, for predictable escaping.
 sys.path.insert(0, os.path.normpath(_base_dir +
                    "/../../../../third_party"))
 import simplejson as json
 from directory import Sample
 from directory import ApiManifest
 from directory import SamplesManifest
 
-def RenderPages(names, dump_render_tree):
-  """
-  Calls DumpRenderTree .../generator.html?<names> and writes the
-  results to .../docs/<name>.html
-  """
-  if not names:
-    raise Exception("RenderPage called with empty names param")
+def RenderPages(family, dump_render_tree, single_page_name):
+  output_dir = os.path.join(_base_dir, family)
+  names = set(os.path.splitext(name)[0] for name in os.listdir(output_dir)
+              if not name.startswith(".") and name.endswith(".html"))
+
+  # Allow the user to render a single page if they want
+  if single_page_name:
+    if single_page_name in names:
+      names = [single_page_name]
+    else:
+      return []

[Yoyo Zhou, 2012/06/22 19:05:55]

Silently fail? The old code threw an exception.

[Aaron Boodman, 2012/06/22 22:16:48]

We now run this function twice: once with extensions and once with apps. It can
be possible that the single page specified is not in one of those sets
legitimately.

I don't think the exception was that useful.

[Yoyo Zhou, 2012/06/22 22:26:06]

I guess the user would be told that there were no changes.

 
   generator_url = "file:" + urllib.pathname2url(_generator_html)
-  generator_url += "?" + ",".join(names)
+  generator_url += "?" + family + "|" + ",".join(names)
 
   # Start with a fresh copy of page shell for each file.
   # Save the current contents so that we can look for changes later.
   originals = {}
   for name in names:
-    input_file = _base_dir + "/" + name + ".html"
+    input_file = os.path.join(output_dir, name + ".html")

[Yoyo Zhou, 2012/06/22 19:05:55]

input_file looks like the wrong name for this. More like output_file.

[Aaron Boodman, 2012/06/22 22:16:48]

Done.

 
     if (os.path.isfile(input_file)):
       originals[name] = open(input_file, 'rb').read()
       os.remove(input_file)
     else:
       originals[name] = ""
 
     shutil.copy(_page_shell_html, input_file)
 
   # Run DumpRenderTree and capture result
@@ skipping 26 matching lines @@
   for name in names:
     result = output_parsed[name].encode("utf8") + '\n'
 
     # Remove CRs that are appearing from captured DumpRenderTree output.
     result = result.replace('\r', '')
 
     # Remove empty style attributes.
     result = result.replace(' style=""', '')
 
     # Remove page_shell
-    input_file = _base_dir + "/" + name + ".html"
+    input_file = os.path.join(output_dir, name + ".html")
     os.remove(input_file)
 
     # Write output
     open(input_file, 'wb').write(result)
     if (originals[name] and result != originals[name]):
       changed_files.append(input_file)
 
   return changed_files
 
 
@@ skipping 34 matching lines @@
   for loc in search_locations:
     if os.path.isfile(loc):
       return loc
 
   raise Exception("Could not find DumpRenderTree executable\n"
                   "**DumpRenderTree may need to be built**\n"
                   "Searched: \n" + "\n".join(search_locations) + "\n"
                   "To specify a path to DumpRenderTree use "
                   "--dump-render-tree-path")
 
-def GetStaticFileNames():
-  static_files = os.listdir(_static_dir)
-  return set(os.path.splitext(file_name)[0]
-             for file_name in static_files
-             if file_name.endswith(".html") and not file_name.startswith("."))
-
 def main():
   # Prevent windows from using cygwin python.
   if (sys.platform == "cygwin"):
     sys.exit("Building docs not supported for cygwin python. Please run the "
              "build.sh script instead, which uses depot_tools python.")
 
   parser = OptionParser()
   parser.add_option("--dump-render-tree-path", dest="dump_render_tree_path",
                     metavar="PATH",
                     help="path to DumpRenderTree executable")
   parser.add_option("--page-name", dest="page_name", metavar="PAGE",
                     help="only generate docs for PAGE.html")
   parser.add_option("--nozip", dest="zips", action="store_false",
                     help="do not generate zip files for samples",
                     default=True)
   options, args = parser.parse_args()
 
   if (options.dump_render_tree_path and
       os.path.isfile(options.dump_render_tree_path)):
     dump_render_tree = options.dump_render_tree_path
   else:
     dump_render_tree = FindDumpRenderTree()
 
   # Load the manifest of existing API Methods
   api_manifest = ApiManifest(_extension_api_json_schemas,
                              _extension_api_idl_schemas)
 
-  # Read static file names
-  static_names = GetStaticFileNames()
-
-  # Read module names
-  module_names = api_manifest.getModuleNames()
-
-  # All pages to generate
-  page_names = static_names | module_names
-
-  # Allow the user to render a single page if they want
-  if options.page_name:
-    if options.page_name in page_names:
-      page_names = [options.page_name]
-    else:
-      raise Exception("--page-name argument must be one of %s." %
-                      ', '.join(sorted(page_names)))
-
   # Write temporary JSON files based on the IDL inputs
   api_manifest.generateJSONFromIDL()
 
   # Render a manifest file containing metadata about all the extension samples
   samples_manifest = SamplesManifest(_samples_dir, _base_dir, api_manifest)
   samples_manifest.writeToFile(_samples_json)
 
   # Write zipped versions of the samples listed in the manifest to the
   # filesystem, unless the user has disabled it
+  modified_files = []
   if options.zips:
-    modified_zips = samples_manifest.writeZippedSamples()
-  else:
-    modified_zips = []
+    modified_files.extend(samples_manifest.writeZippedSamples())
 
-  modified_files = RenderPages(page_names, dump_render_tree)
-  modified_files.extend(modified_zips)
+  doc_families = ["extensions", "apps"]
+  for family in doc_families:
+    modified_files.extend(
+        RenderPages(family, dump_render_tree, options.page_name))
 
   if len(modified_files) == 0:
     print "Output files match existing files. No changes made."
   else:
     print ("ATTENTION: EXTENSION DOCS HAVE CHANGED\n" +
            "The following files have been modified and should be checked\n" +
            "into source control (ideally in the same changelist as the\n" +
            "underlying files that resulting in their changing).")
     for f in modified_files:
       print " * %s" % f
 
   # Hack. Sleep here, otherwise windows doesn't properly close the debug.log
   # and the os.remove will fail with a "Permission denied".
   time.sleep(1)
   debug_log = os.path.normpath(_build_dir + "/" + "debug.log")
   if (os.path.isfile(debug_log)):
     os.remove(debug_log)
 
   # Cleanup our temporary IDL->JSON files
   api_manifest.cleanupGeneratedFiles()
 
   if 'EX_OK' in dir(os):
     return os.EX_OK
   else:
     return 0
 
 if __name__ == '__main__':
   sys.exit(main())