Dynamically generate a heading for Extension Docs API pages

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

 # 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.
 
 import copy
 import logging
 import os
 
 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
 
 # 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):
     if item.get('nodoc', False):
       return True
     to_remove = []
     for key, value in item.items():
       if _RemoveNoDocs(value):
         to_remove.append(key)
     for k in to_remove:
@@ skipping 15 matching lines @@
 def _FormatValue(value):
   """Inserts commas every three digits for integer values. It is magic.
   """
   s = str(value)
   return ','.join([s[max(0, i - 3):i] for i in range(len(s), 0, -3)][::-1])
 
 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
     else:
       self._namespace = model.Namespace(clean_json, clean_json['namespace'])
 
   def _FormatDescription(self, description):
     if self._disable_refs:
       return description
     return self._ref_resolver.ResolveAllLinks(description,
                                               namespace=self._namespace.name)
 
   def _GetLink(self, link):
     if self._disable_refs:
       type_name = link.split('.', 1)[-1]
       return { 'href': '#type-%s' % type_name, 'text': link, 'name': link }
     return self._ref_resolver.SafeGetLink(link, namespace=self._namespace.name)
 
   def ToDict(self):
     if self._namespace is None:
       return {}
+    availability = self._HandleAvailability()

[not at google - send to devlin, 2013/04/02 10:29:39]

inline?

[epeterson, 2013/04/03 01:21:43]

Done.

     return {
       'name': self._namespace.name,
+      'description': self._namespace.description,
+      'availability': availability,
       '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:

[not at google - send to devlin, 2013/04/02 10:29:39]

when is there no availability data source?

[epeterson, 2013/04/03 01:21:43]

Each channel instance has an APIDataSourceFactory containing an availability
data source. 

The global chrome version data source is passed a method upon construction that
allows it to create APIDataSources for the purpose of checking for the existence
of APIs using TryGet(). These APIDataSources do not need an availability data
source. 

+      return self._availability_data_source.FindEarliestAvailability(
+         self._namespace.name)
+
+  def _HandleAvailability(self):
+    """Finds the availability for an api, and creates a string describing
+    the availability depending on its original format.
+    """
+    availability = self._namespace.availability
+    availability_string = 'Not currently available'
+    # Check to see if the .json/.idl already contains an availability field.
+    if availability is None:
+      availability = self._GetAvailability()
+
+    if availability is not None:
+      if availability.isdigit():
+        availability_string = 'Google Chrome %s' % availability
+      else:
+        availability_string = ('Google Chrome %s Channel Only' %
+            availability.capitalize())
+    return availability_string

[not at google - send to devlin, 2013/04/02 10:29:39]

All of this string logic needs to be embedded in the templates, it's not really
a concern of the server (or more pragmatically, we need to be able to tweak
wording and layout without needing a server push).

Perhaps we need to return an object with {'version': <the version number>, ...
}. The data to include there is interesting - what would also be cool is if we
could show like "has been stable for 3 years" or whatever there. So like

Availability: trunk <whatever wording we decide to use here>
Availability: Google Chrome 26 - dev channel
Availability: Google Chrome 25 - beta and dev channel
Availability: Google Chrome 24 - stable since 2013/03/01 (2+ weeks)

So that might involve like, to borrow IDL syntax,

dictionary Availability {
  int version;
  bool? beta;
  bool? dev;
  bool? trunk;
  StableAvailability? stable;
}

dictionary StableAvailability {
  string duration;  // e.g. "3+ years", "2+ months"
  string since;  // e.g. "2013/03/01"
}

[not at google - send to devlin, 2013/04/02 21:58:16]

Ok - so I think it's fine to submit the server changes once the object model is
right, without needing to fine-tune what the templates look like. We can do that
separately.

+
   def _GenerateTypes(self, types):
     return [self._GenerateType(t) for t in types]
 
   def _GenerateType(self, type_):
     type_dict = {
       'name': type_.simple_name,
       'description': self._FormatDescription(type_.description),
       'properties': self._GenerateProperties(type_.properties),
       'functions': self._GenerateFunctions(type_.functions),
       'events': self._GenerateEvents(type_.events),
@@ skipping 167 matching lines @@
   def get(self, key):
     return self._samples.FilterSamples(key, self._api_name)
 
 class APIDataSource(object):
   """This class fetches and loads JSON APIs from the FileSystem passed in with
   |cache_factory|, so the APIs can be plugged into templates.
   """
   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)
       self._json_cache = cache_factory.Create(
           lambda api_name, api: self._LoadJsonAPI(api, False),
           compiled_fs.JSON,
           version=_VERSION)
       self._idl_cache = cache_factory.Create(
           lambda api_name, api: self._LoadIdlAPI(api, False),
           compiled_fs.IDL,
@@ skipping 10 matching lines @@
           lambda api_name, api: self._LoadIdlAPI(api, True),
           compiled_fs.IDL_NO_REFS,
           version=_VERSION)
       self._idl_names_cache = cache_factory.Create(self._GetIDLNames,
                                                    compiled_fs.IDL_NAMES,
                                                    version=_VERSION)
       self._names_cache = cache_factory.Create(self._GetAllNames,
                                                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
 
     def SetSamplesDataSourceFactory(self, samples_data_source_factory):
       self._samples_data_source_factory = samples_data_source_factory
 
     def SetReferenceResolverFactory(self, ref_resolver_factory):
       self._ref_resolver_factory = ref_resolver_factory
 
@@ skipping 25 matching lines @@
                            samples,
                            disable_refs)
 
     def _LoadPermissions(self, file_name, json_str):
       return json_parse.Parse(json_str)
 
     def _LoadJsonAPI(self, api, disable_refs):
       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 [
         model.UnixName(os.path.splitext(api[len('%s/' % self._base_path):])[0])
         for api in apis if api.endswith('.idl')
       ]
 
     def _GetAllNames(self, base_dir, apis):
       return [
         model.UnixName(os.path.splitext(api[len('%s/' % self._base_path):])[0])
@@ skipping 61 matching lines @@
     return feature_data
 
   def _GenerateHandlebarContext(self, handlebar_dict, path):
     handlebar_dict['permissions'] = self._GetFeatureData(path)
     handlebar_dict['samples'] = _LazySamplesGetter(path, self._samples)
     return handlebar_dict
 
   def _GetAsSubdirectory(self, name):
     if name.startswith('experimental_'):
       parts = name[len('experimental_'):].split('_', 1)
-      parts[1] = 'experimental_%s' % parts[1]
-      return '/'.join(parts)
+      if len(parts) > 1:
+        parts[1] = 'experimental_%s' % parts[1]
+        return '/'.join(parts)
+      else:
+        return '%s/%s' % (parts[0], name)
     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
           (self._json_cache_no_refs, '.json'))
     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, try_non_unix=False):

[not at google - send to devlin, 2013/04/02 10:29:39]

Note to future self: unclear what this should be returning, perhaps solidifying
this as a HasApi method and returning a bool would be clearer.

[epeterson, 2013/04/03 03:59:57]

You're right, it doesn't make sense to return an unused object here, I was a
little wary of this before.

I tried to implement your idea, but the exception handling looks messy.

+    """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 try_non_unix 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 model.ParseException as e:
+      # Some APIs in older versions trip up the JSC (i.e. v.18 tabs.json lacks
+      # a "type" attribute for its "url" property)
+      logging.warning('Caught parse exception for %s: %s' % (unix_name, e))
+      return {}