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 9695fd6dcebed8a20b8653c536f31dafa4272e1b..07f5eea9cf2f021d374ba8886c62cbe546c3f11d 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -2,11 +2,13 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+import collections
 import copy
+import json as json_library
 import logging
 import os
-import collections
 
+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
@@ -28,7 +30,6 @@ def _RemoveNoDocs(item):
       item.remove(i)
   return False
 
-
 def _InlineDocs(schema):
   """Replace '$ref's that refer to inline_docs with the json for those docs.
   """
@@ -80,9 +81,18 @@ 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,
+               create_file_system):
     self._ref_resolver = ref_resolver
     self._disable_refs = disable_refs
+    self._availability_data_source = availability_data_source
+    trunk_file_system = create_file_system('trunk')
+    self._intro_tables = json_parse.Parse(trunk_file_system.ReadSingle(
+        '%s/intro_tables.json' % svn_constants.JSON_PATH))

[not at google - send to devlin, 2013/05/13 21:26:41]

I don't think *this* should be trunk though should it? Just the ones that go
into the availability data source?

The permissions/intro is whatever the host file system says it is?

Also since these are shared across multiple object you should probably cache it
- therefore, try using the compiled_fs with a populate_fn that does this
json_parse stuff. It might even be enough to do

_json_cache = compiled_fs_factory.Create(json_parse.Parse, APIDataSource)

?

[epeterson, 2013/05/15 07:38:34]

Done.

     clean_json = copy.deepcopy(json)
     if _RemoveNoDocs(clean_json):
       self._namespace = None
@@ -107,12 +117,48 @@ class _JSCModel(object):
       return {}
     return {
       'name': self._namespace.name,
+      'description': self._namespace.description,
+      'availability': self._GetAvailability(),
+      'experimental': self._CheckExperimental(),
+      'permissions_': self._GetPermissions(),

[epeterson, 2013/05/13 02:38:10]

'permissions' is already reserved. There's a note about this in
intro_tables.html as well.

[not at google - send to devlin, 2013/05/13 21:26:41]

Ohh. Why is it reserved?? Bummer, ok, well permissions_ is pretty confusing
then. Maybe api_permissions?

[epeterson, 2013/05/15 07:38:34]

Done.

+      'learn_more': self._GetMoreLearning(),
       '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):
+    """Finds the earliest stable version of chrome where an API was available
+    using AvailabilityDataSource. If an API hasn't been released to stable yet,
+    then the development channel that the API is currently available on will
+    be returned instead.
+    """
+    if not self._CheckExperimental():
+      return self._availability_data_source.GetAvailability(
+          self._namespace.name)
+    # A special message for experimental APIs' availability will be displayed.
+    return None
+
+  def _CheckExperimental(self):
+     return self._namespace.name.startswith('experimental')
+
+  def _GetPermissions(self):
+    """This is a temporary fix for generating API intro tables automatically.
+    Information on an API's permissions is pulled from a json file so that it
+    can be sent to the templates along with other relevant intro data.
+    """
+    table_info = self._intro_tables.get(self._namespace.name)
+    return table_info.get('Permissions') if table_info else None
+
+  def _GetMoreLearning(self):

[not at google - send to devlin, 2013/05/13 21:26:41]

that is an amusing name :) I don't think that pluralising Lean More is More
Learning. Whatevs.

+    """We can't automatically generate the "Learn more" field in an API's.
+    intro table; instead, we pull it from a json file so that it can be sent to
+    the templates along with other relevant intro data.
+    """
+    table_info = self._intro_tables.get(self._namespace.name)
+    return table_info.get('LearnMore') if table_info else None
+
   def _GenerateTypes(self, types):
     return [self._GenerateType(t) for t in types]
 
@@ -299,7 +345,11 @@ class APIDataSource(object):
   |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_data_source_factory,
+                 create_file_system):
       def create_compiled_fs(fn, category):
         return compiled_fs_factory.Create(fn, APIDataSource, category=category)
 
@@ -327,7 +377,8 @@ class APIDataSource(object):
       self._names_cache = create_compiled_fs(self._GetAllNames, 'names')
 
       self._base_path = base_path
-
+      self._availability_data_source = availability_data_source_factory.Create()
+      self._create_file_system = create_file_system
       # These must be set later via the SetFooDataSourceFactory methods.
       self._ref_resolver_factory = None
       self._samples_data_source_factory = None
@@ -373,14 +424,18 @@ 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,
+          self._create_file_system).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,
+          self._create_file_system).ToDict()
 
     def _GetIDLNames(self, base_dir, apis):
       return self._GetExtNames(apis, ['idl'])
@@ -457,21 +512,26 @@ class APIDataSource(object):
   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
@@ -479,6 +539,11 @@ 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)