Linking AvailabilityFinder with APIDataSource and intro-table templates.

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
 from collections import defaultdict, Mapping
 
+from branch_utility import BranchUtility
+import svn_constants
 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
 
 def _RemoveNoDocs(item):
   if json_parse.IsDict(item):
     if item.get('nodoc', False):
       return True
     for key, value in item.items():
@@ skipping 76 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, idl=False):
+  def __init__(self,
+               json,
+               ref_resolver,
+               disable_refs,
+               availability_finder,
+               intro_cache,
+               idl=False):
     self._ref_resolver = ref_resolver
     self._disable_refs = disable_refs
+    self._availability_finder = availability_finder
+    self._intro_tables = intro_cache.GetFromFile(
+        '%s/intro_tables.json' % svn_constants.JSON_PATH)
     clean_json = copy.deepcopy(json)
     if _RemoveNoDocs(clean_json):
       self._namespace = None
     else:
       if idl:
         _DetectInlineableTypes(clean_json)
       _InlineDocs(clean_json)
       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 {}
     return {
       'name': self._namespace.name,
-      'description': self._namespace.description,
       '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)
+      'properties': self._GenerateProperties(self._namespace.properties),
+      'intro_list': self._GetIntroTableList()
     }
 
+  def _GetIntroTableList(self):
+    """Create a generic data structure that can be traversed by the templates
+    to create an API intro table.
+    """
+    intro_list = []
+    intro_list.append({
+      'title': 'Description',
+      'content': [
+        { 'text': self._FormatDescription(self._namespace.description) }
+      ]
+    })

[not at google - send to devlin, 2013/07/16 22:25:00]

more concise:

intro_list = [{
  'title': 'Description',
  'content': ...
}]

[epeterson, 2013/07/17 23:48:23]

Done.

+
+    availability = None
+    if self._IsExperimental():
+      status = 'experimental'
+    else:
+      availability = self._GetApiAvailability()
+      status = availability.channel
+    intro_list.append({
+      'title': 'Availability',
+      'content': [
+        {
+          'message': True,
+          status: True,
+          'version': availability.version if status == 'stable' else None

[not at google - send to devlin, 2013/07/16 22:25:00]

maybe hold onto version rather than availability, to avoid awkward python
ternary syntax.

[epeterson, 2013/07/17 23:48:23]

Done.

+        }

[epeterson, 2013/07/16 00:28:23]

I tried a lot of different things here.

I couldn't get something like the 
  {{?partial}}{{+partial}}{{/partial}} 
idea to work, but I may have been approaching it the wrong way.

Currently, this information will get passed to the availability_messages partial
template because 'message' resolves to true. 

status will be the name of the channel, or 'experimental', which
availability_messages will check and provide an appropriate message for.

'version' will be included as {{version}} {{?stable}} evaluates to true in the
availability_messages (status == 'stable' here).

[not at google - send to devlin, 2013/07/16 22:25:00]

I think you could combine message and status into a single partial argument.

You'd set the partial to whatever the status implies it to be. so if it's dev,
retrieve the template for the dev warning, and pass it that.

[epeterson, 2013/07/17 23:48:23]

Done. But I had to add in extra logic to pass in a compiled_fs for retrieving
templates and giving them to Handlebar().

+      ]
+    })
+
+    # Look up the API name in intro_tables.json, which is structured similarly
+    # to the data structure being created. If the name is found, loop through
+    # the attributes and add them to this structure.
+    table_info = self._intro_tables.get(self._namespace.name)
+    if table_info is None:
+      return intro_list
+
+    # The intro tables have a specific ordering that needs to be followed.
+    ordering = ('Permissions', 'Samples', 'Learn More')
+
+    for category in ordering:
+      if category in table_info.keys():
+        intro_list.append({
+          'title': category,
+          'content': table_info.get(category, [])
+        })
+    return intro_list
+
+  def _GetApiAvailability(self):
+    return self._availability_finder.GetApiAvailability(self._namespace.name)
+
+  def _IsExperimental(self):
+     return self._namespace.name.startswith('experimental')
+
   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 166 matching lines @@
     self._samples = samples
 
   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
   |compiled_fs_factory|, so the APIs can be plugged into templates.
   """
   class Factory(object):
-    def __init__(self, compiled_fs_factory, base_path):
+    def __init__(self,
+                 compiled_fs_factory,
+                 base_path,
+                 availability_finder_factory):
       def create_compiled_fs(fn, category):
         return compiled_fs_factory.Create(fn, APIDataSource, category=category)
 
       self._permissions_cache = create_compiled_fs(self._LoadPermissions,
                                                    'permissions')
 
       self._json_cache = create_compiled_fs(
           lambda api_name, api: self._LoadJsonAPI(api, False),
           'json')
       self._idl_cache = create_compiled_fs(
           lambda api_name, api: self._LoadIdlAPI(api, False),
           'idl')
 
       # These caches are used if an APIDataSource does not want to resolve the
       # $refs in an API. This is needed to prevent infinite recursion in
       # ReferenceResolver.
       self._json_cache_no_refs = create_compiled_fs(
           lambda api_name, api: self._LoadJsonAPI(api, True),
           'json-no-refs')
       self._idl_cache_no_refs = create_compiled_fs(
           lambda api_name, api: self._LoadIdlAPI(api, True),
           'idl-no-refs')
 
       self._idl_names_cache = create_compiled_fs(self._GetIDLNames, 'idl-names')
       self._names_cache = create_compiled_fs(self._GetAllNames, 'names')
 
       self._base_path = base_path
-
+      self._availability_finder = availability_finder_factory.Create()
+      self._intro_cache = create_compiled_fs(
+          lambda _, json: json_parse.Parse(json),
+          'intro-cache')
       # 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_finder,
+          self._intro_cache).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,
+          self._availability_finder,
+          self._intro_cache,
           idl=True).ToDict()
 
     def _GetIDLNames(self, base_dir, apis):
       return self._GetExtNames(apis, ['idl'])
 
     def _GetAllNames(self, base_dir, apis):
       return self._GetExtNames(apis, ['json', 'idl'])
 
     def _GetExtNames(self, apis, exts):
       return [model.UnixName(os.path.splitext(api)[0]) for api in apis
@@ skipping 57 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)
+      return '%s/%s' % (parts[0], name)
     return name.replace('_', '/', 1)
 
   def get(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)
 
     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 self._GenerateHandlebarContext(
         cache.GetFromFile('%s/%s%s' % (self._base_path, unix_name, ext)),
         path)