Linking AvailabilityFinder with APIDataSource and intro-table templates.

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 3fdd37587de23c6e4c8eab94d7958da966880ae4..5eed706c9c50ff4ed3364cb67f2726316688e8e5 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -3,10 +3,12 @@
 # found in the LICENSE file.
 
 import copy
+import json as json_library

[not at google - send to devlin, 2013/07/03 19:54:56]

not used?

[epeterson, 2013/07/09 20:51:18]

Done.

 import logging
 import os
 from collections import defaultdict, Mapping
 
+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
@@ -103,9 +105,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, 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
@@ -133,12 +144,51 @@ class _JSCModel(object):
     return {
       'name': self._namespace.name,
       'description': self._namespace.description,
+      'availability': self._GetApiAvailability(),
+      'experimental': self._CheckExperimental(),
+      'api_permissions': self._GetPermissions(),
+      '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 _GetApiAvailability(self):
+    """Finds the earliest stable version of chrome where an API was available
+    using AvailabilityFinder. 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():
+      availability = self._availability_finder.GetApiAvailability(
+          self._namespace.name)
+      if availability:
+        if availability.channel == 'stable':
+          return availability.version
+        return availability.channel
+    # A special message for experimental APIs' availability will be displayed.
+    return None

[not at google - send to devlin, 2013/07/03 19:54:56]

invert the condition here:

if self._CheckExperimental():
  # A special message...
  return None
...

[epeterson, 2013/07/09 20:51:18]

Done.

+
+  def _CheckExperimental(self):

[not at google - send to devlin, 2013/07/03 19:54:56]

IsExperimental

[epeterson, 2013/07/09 20:51:18]

Done.

+     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/07/08 17:08:02]

Update: this actually needs to be more generic. See here:

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...

I think we'll need to slightly redesign this stuff to pass just a list of data
to the templates, and have it render in a generic way. Like, a list of tuples
like (title, content), where
- title would be something like "Description", "availability", etc.
- content would be a rich structure that captures what needs to be rendered.
this includes
  - the text to render
  - whether it's a link, in which case the link URL
  - what the style is
  - in fact it would probably be a list of such things.

So the example linked to above, it would be structure like:

[
  { "title": "Description",
    "content": [ { "text": "Use the Chrome In-App..." } ]
  },
  { "title": "Availability",
    "content": [ { "text": "Stable since version 29" } ]
  },
  { "title": "Samples",
    "content": [ { "link": "http://...", "text": "in-app-payments" } ]
  },
  { "title": "Learn more",
    "content": [
      { "link": "...", "text": "Google Wallet" },
      { "link": "...", "text": "Google Wallet for Digital Goods" }
    ]
  }
]

Now, the first two of those - Description/Availability - we can generate in the
way that you already are (description from the json, availability from logic +
those hard-coded things in the JSON. For availability though, we'll need to
generate a "class" property which would be "dev" or "beta" etc to include the
colour.

The others - samples/permission/learn more - we can generate from that other
JSON thing you've written, with the "permissions" later being automatically
generated.

+    """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]
 
@@ -325,7 +375,10 @@ 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_finder_factory):
       def create_compiled_fs(fn, category):
         return compiled_fs_factory.Create(fn, APIDataSource, category=category)
 
@@ -353,7 +406,10 @@ class APIDataSource(object):
       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
@@ -399,7 +455,9 @@ 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_finder,
+          self._intro_cache).ToDict()
 
     def _LoadIdlAPI(self, api, disable_refs):
       idl = idl_parser.IDLParser().ParseData(api)
@@ -407,6 +465,8 @@ class APIDataSource(object):
           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):
@@ -484,8 +544,10 @@ 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)
+      return '%s/%s' % (parts[0], name)
     return name.replace('_', '/', 1)
 
   def get(self, key):