Linking AvailabilityFinder with APIDataSource and intro-table templates.

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

Index: chrome/common/extensions/docs/server2/availability_finder.py
diff --git a/chrome/common/extensions/docs/server2/availability_finder.py b/chrome/common/extensions/docs/server2/availability_finder.py
index 4105703e3fd886d70feb828d4b9a259adedd6506..73bf858140359b7797b1b043aeedf16ec27f5230 100644
--- a/chrome/common/extensions/docs/server2/availability_finder.py
+++ b/chrome/common/extensions/docs/server2/availability_finder.py
@@ -19,6 +19,9 @@ _MANIFEST_FEATURES = svn_constants.API_PATH + '/_manifest_features.json'
 _PERMISSION_FEATURES = svn_constants.API_PATH + '/_permission_features.json'
 _STABLE = 'stable'
 
+_EXPERIMENTAL_MESSAGE = ('Experimental only (see' +
+    '<a href="experimental.html#using">How to use experimental APIs</a>).')

[not at google - send to devlin, 2013/07/09 23:11:55]

ah. so maybe we need to actually pass _templates_ into that table? definitely
can't be embedding HTML in the server code.

so like, allow passing a 'partial' argument as well (like 'text'), then the
intro content would look something like

{{?link ... }}
{{?class ... }}
{{?text text /}}
{{?partial +partial /}}
{{?class...}}
{{?link ...}}

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

Solution to this no longer involves availability_finder for HTML, which is good.
The logic is over in api_data_source.

+
 class AvailabilityInfo(object):
   def __init__(self, channel, version):
     self.channel = channel
@@ -44,7 +47,7 @@ def _GetChannelFromFeatures(api_name, file_system, path):
 def _GetChannelFromApiFeatures(api_name, file_system):
   try:
     return _GetChannelFromFeatures(api_name, file_system, _API_FEATURES)
-  except FileNotFoundError as e:
+  except FileNotFoundError:
     # TODO(epeterson) Remove except block once _api_features is in all channels.
     return None
 
@@ -75,7 +78,7 @@ def _ExistsInExtensionApi(api_name, file_system):
     api_rows = [row.get('namespace') for row in extension_api_json
                 if 'namespace' in row]
     return True if api_name in api_rows else False
-  except FileNotFoundError as e:
+  except FileNotFoundError:
     # This should only happen on preview.py since extension_api.json is no
     # longer present in trunk.
     return False
@@ -153,6 +156,7 @@ class AvailabilityFinder(object):
         # SVN data isn't available below version 5.
         return version + 1
       available = False
+      available_channel = None
       features_fs, names_fs = self._CreateFeaturesAndNamesFileSystems(version)
       if version >= 28:
         # The _api_features.json file first appears in version 28 and should be
@@ -161,14 +165,17 @@ class AvailabilityFinder(object):
         # are present in Chrome 20 and onwards. Fall back to a check for file
         # system existence if the API is not stable in any of the _features.json
         # files.
-        available = _GetChannelFromApiFeatures(api_name, features_fs) == _STABLE
+        available_channel = _GetChannelFromApiFeatures(api_name, features_fs)
       if version >= 20:
         # Check other _features.json files/file existence if the API wasn't
         # found in _api_features.json, or if _api_features.json wasn't present.
-        available = available or (
-            _GetChannelFromPermissionFeatures(api_name, features_fs) == _STABLE
-            or _GetChannelFromManifestFeatures(api_name, features_fs) == _STABLE
-            or _ExistsInFileSystem(api_name, names_fs))
+        available_channel = available_channel or (
+            _GetChannelFromPermissionFeatures(api_name, features_fs)
+            or _GetChannelFromManifestFeatures(api_name, features_fs))
+        if available_channel is None:
+          available = _ExistsInFileSystem(api_name, names_fs)
+        else:
+          available = available_channel == _STABLE
       elif version >= 18:
         # These versions are a little troublesome. Version 19 has
         # _permission_features.json, but it lacks 'channel' information.
@@ -190,16 +197,16 @@ class AvailabilityFinder(object):
     the channel that the given API is determined to be available on.
     '''
     features_fs, names_fs = self._CreateFeaturesAndNamesFileSystems(version)
-    channel = (_GetChannelFromApiFeatures(api_name, features_fs)
-               or _GetChannelFromPermissionFeatures(api_name, features_fs)
-               or _GetChannelFromManifestFeatures(api_name, features_fs))
-    if channel is None and _ExistsInFileSystem(api_name, names_fs):
+    available_channel = (_GetChannelFromApiFeatures(api_name, features_fs)
+        or _GetChannelFromPermissionFeatures(api_name, features_fs)
+        or _GetChannelFromManifestFeatures(api_name, features_fs))
+    if available_channel is None and _ExistsInFileSystem(api_name, names_fs):
       # If an API is not represented in any of the _features files, but exists
       # in the filesystem, then assume it is available in this version.
       # The windows API is an example of this.
       return self._branch_utility.GetChannelForVersion(version)
 
-    return channel
+    return available_channel
 
   def GetApiAvailability(self, api_name):
     '''Determines the availability for an API by testing several scenarios.
@@ -245,3 +252,16 @@ class AvailabilityFinder(object):
 
     self._object_store.Set(api_name, availability)
     return availability
+
+  @staticmethod
+  def StringifyAvailability(availability):
+    '''Given an AvailabilityInfo struct, provides a message that can be
+    displayed in an API intro table
+    '''
+    availability_id = 'intro-availability'
+    if availability.channel == 'stable':
+      return '<span id="%s" class="%s">Stable</span> since version %s.' % (
+          availability_id, availability.channel, availability.version)
+    else:
+      return 'Available on <span id="%s" class="%s">%s</span>.' % (
+          availability_id, availability.channel, availability.channel)

[not at google - send to devlin, 2013/07/09 23:11:55]

Yeah ok so same thing with the partials. We'll need to to some tweaking of the
language. Maybe for the beta version it shlud be

"<a ...>Beta and dev channels</a> only"

dev

"<a...>Dev channel</a> only"

trunk

"Only when <a>built from source</a>"

and we can add the same links there that we already have for the warnings.

oh and, the screenshots look awesome but it makes me realise that the colours
there are actually really confusing, so let's give up on that avenue :( sorry.

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

Done.