Dynamically generate a heading for Extension Docs API pages

chrome/common/extensions/docs/server2/api_data_source.py

Index: chrome/common/extensions/docs/server2/api_data_source.py
diff --git a/chrome/common/extensions/docs/server2/api_data_source.py b/chrome/common/extensions/docs/server2/api_data_source.py
index 08369f0e68c35be11ef55dea02988c57c2172740..43ef1c82bba8c19dc3a02991c92731d03bea96e7 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -5,19 +5,19 @@
 import copy
 import logging
 import os

[cduvall, 2013/03/21 18:43:53]

Add the newline back in after this (separates python stdlib includes from your
files)

[epeterson, 2013/03/25 19:35:11]

Done.

-
 import compiled_file_system as compiled_fs
 from file_system import FileNotFoundError
 import third_party.json_schema_compiler.json_parse as json_parse
 import third_party.json_schema_compiler.model as model
 import third_party.json_schema_compiler.idl_schema as idl_schema
 import third_party.json_schema_compiler.idl_parser as idl_parser
+from third_party.json_schema_compiler.model import ParseException
 
 # Increment this version when there are changes to the data stored in any of
 # the caches used by APIDataSource. This would include changes to model.py in
 # JSON schema compiler! This allows the cache to be invalidated without having
 # to flush memcache on the production server.
-_VERSION = 15
+_VERSION = 16
 
 def _RemoveNoDocs(item):
   if json_parse.IsDict(item):
@@ -53,9 +53,14 @@ class _JSCModel(object):
   """Uses a Model from the JSON Schema Compiler and generates a dict that
   a Handlebar template can use for a data source.
   """
-  def __init__(self, json, ref_resolver, disable_refs):
+  def __init__(self,
+               json,
+               ref_resolver,
+               disable_refs,
+               availability_data_source=None):
     self._ref_resolver = ref_resolver
     self._disable_refs = disable_refs
+    self._availability_data_source = availability_data_source
     clean_json = copy.deepcopy(json)
     if _RemoveNoDocs(clean_json):
       self._namespace = None
@@ -77,14 +82,38 @@ class _JSCModel(object):
   def ToDict(self):
     if self._namespace is None:
       return {}
+    if self._namespace.availability is None:
+      availability = self._GetAvailability()
+      if availability is not None:
+        #availability found using filesystem

[cduvall, 2013/03/21 18:43:53]

Space after # in all comments.

[epeterson, 2013/03/25 19:35:11]

Done.

+        availability_generated = True
+      else:
+        #we don't know anything about this api's availability
+        availability = None

[cduvall, 2013/03/21 18:43:53]

No need to set to None, we already know it is

[epeterson, 2013/03/25 19:35:11]

Done.

+        availability_generated = None

[cduvall, 2013/03/21 18:43:53]

Should be False not None

[epeterson, 2013/03/25 19:35:11]

Done.

+    else:
+      #availability was already present in a .json/.idl file
+      availability = self._namespace.availability
+      availability_generated = None

[cduvall, 2013/03/21 18:43:53]

Just set availability and availability_generated at the beginning of this
function:

availability = self._namespace.availability
availability_generated = False
if availability is None:
  ...

[epeterson, 2013/03/25 19:35:11]

Done.

     return {
       'name': self._namespace.name,
+      'description': self._namespace.description,
+      'availability': availability,
+      'availability_generated': availability_generated,
       'types': self._GenerateTypes(self._namespace.types.values()),
       'functions': self._GenerateFunctions(self._namespace.functions),
       'events': self._GenerateEvents(self._namespace.events),
       'properties': self._GenerateProperties(self._namespace.properties)
     }
 
+  def _GetAvailability(self):
+    """Returns the earliest version of chrome, represented by a version number,
+       that this api was available in
+    """
+    if self._availability_data_source is not None:
+      return self._availability_data_source.FindEarliestAvailability(
+         self._namespace.name)
+
   def _GenerateTypes(self, types):
     return [self._GenerateType(t) for t in types]
 
@@ -272,7 +301,8 @@ class APIDataSource(object):
   class Factory(object):
     def __init__(self,
                  cache_factory,
-                 base_path):
+                 base_path,
+                 availability_data_source=None):
       self._permissions_cache = cache_factory.Create(self._LoadPermissions,
                                                      compiled_fs.PERMS,
                                                      version=_VERSION)
@@ -303,7 +333,7 @@ class APIDataSource(object):
                                                compiled_fs.NAMES,
                                                version=_VERSION)
       self._base_path = base_path
-
+      self._availability_data_source = availability_data_source
       # These must be set later via the SetFooDataSourceFactory methods.
       self._ref_resolver_factory = None
       self._samples_data_source_factory = None
@@ -349,14 +379,16 @@ class APIDataSource(object):
       return _JSCModel(
           json_parse.Parse(api)[0],
           self._ref_resolver_factory.Create() if not disable_refs else None,
-          disable_refs).ToDict()
+          disable_refs,
+          self._availability_data_source).ToDict()
 
     def _LoadIdlAPI(self, api, disable_refs):
       idl = idl_parser.IDLParser().ParseData(api)
       return _JSCModel(
           idl_schema.IDLSchema(idl).process()[0],
           self._ref_resolver_factory.Create() if not disable_refs else None,
-          disable_refs).ToDict()
+          disable_refs,
+          self._availability_data_source).ToDict()
 
     def _GetIDLNames(self, base_dir, apis):
       return [
@@ -442,17 +474,19 @@ class APIDataSource(object):
       return '/'.join(parts)
     return name.replace('_', '/', 1)
 
-  def get(self, key):
+  def _DetermineNamesForGet(self, key):
     if key.endswith('.html') or key.endswith('.json') or key.endswith('.idl'):
       path, ext = os.path.splitext(key)
     else:
       path = key
     unix_name = model.UnixName(path)
-    idl_names = self._idl_names_cache.GetFromFileListing(self._base_path)
     names = self._names_cache.GetFromFileListing(self._base_path)
     if unix_name not in names and self._GetAsSubdirectory(unix_name) in names:
       unix_name = self._GetAsSubdirectory(unix_name)
+    return (path, unix_name)
 
+  def _DetermineCacheForGet(self, unix_name):
+    idl_names = self._idl_names_cache.GetFromFileListing(self._base_path)
     if self._disable_refs:
       cache, ext = (
           (self._idl_cache_no_refs, '.idl') if (unix_name in idl_names) else
@@ -460,6 +494,28 @@ class APIDataSource(object):
     else:
       cache, ext = ((self._idl_cache, '.idl') if (unix_name in idl_names) else
                     (self._json_cache, '.json'))
+    return (cache, ext)
+
+  def get(self, key):
+    path, unix_name = self._DetermineNamesForGet(key)
+    cache, ext = self._DetermineCacheForGet(unix_name)
     return self._GenerateHandlebarContext(
         cache.GetFromFile('%s/%s%s' % (self._base_path, unix_name, ext)),
         path)
+
+  def tryGet(self, key, tryNonUnix=False):

[cduvall, 2013/03/21 18:43:53]

parameter names are unix_hacker_style
method names should be CamelCase with first letter capital.

[epeterson, 2013/03/25 19:35:11]

Done.

+    """Like get(self, key), only doesn't generate and return HandlebarContext.
+    Used for checking existence of an api: cache will raise a FileNotFoundError
+    if an api cannot be located in the cache.
+    """
+    camel_name, unix_name = self._DetermineNamesForGet(key)
+    cache, ext = self._DetermineCacheForGet(unix_name)
+    try:
+      if tryNonUnix is True:
+        return cache.GetFromFile('%s/%s%s' % (self._base_path, camel_name, ext))
+      return cache.GetFromFile('%s/%s%s' % (self._base_path, unix_name, ext))
+    except ParseException:
+      #Some api's in older versions trip up the JSC (i.e. v.18 tabs.json lacks
+      #a "type" attribute for its "url" property)
+      logging.error("Caught Parse Exception")
+      return {}