Extension Docs Server: Include a list of samples used in the api reference page.

BUG=
TEST=


Review URL: https://chromiumcodereview.appspot.com/10835012

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@149690 0039d316-1c4b-4281-b951-d872f2087c98

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

@@ -16,24 +16,42 @@ class APIDataSource(object):
   """This class fetches and loads JSON APIs from the FileSystem passed in with
   |cache_builder|, so the APIs can be plugged into templates.
   """
-  def __init__(self, cache_builder, base_path):
-    self._json_cache = cache_builder.build(self._LoadJsonAPI)
-    self._idl_cache = cache_builder.build(self._LoadIdlAPI)
-    self._permissions_cache = cache_builder.build(self._LoadPermissions)
-    self._base_path = base_path
+  class Factory(object):
+    def __init__(self, cache_builder, base_path, samples_factory):
+      self._permissions_cache = cache_builder.build(self._LoadPermissions)
+      self._json_cache = cache_builder.build(self._LoadJsonAPI)
+      self._idl_cache = cache_builder.build(self._LoadIdlAPI)
+      self._samples_factory = samples_factory
+      self._base_path = base_path
+
+    def Create(self, request):
+      return APIDataSource(self._permissions_cache,
+                           self._json_cache,
+                           self._idl_cache,
+                           self._base_path,
+                           self._samples_factory.Create(request))
+
+    def _LoadPermissions(self, json_str):
+      return json.loads(json_comment_eater.Nom(json_str))
 
-  def _LoadJsonAPI(self, api):
-    generator = HandlebarDictGenerator(
-        json.loads(json_comment_eater.Nom(api))[0])
-    return generator.Generate()
+    def _LoadJsonAPI(self, api):
+      return HandlebarDictGenerator(json.loads(json_comment_eater.Nom(api))[0])
 
-  def _LoadIdlAPI(self, api):
-    idl = idl_parser.IDLParser().ParseData(api)
-    generator = HandlebarDictGenerator(idl_schema.IDLSchema(idl).process()[0])
-    return generator.Generate()
+    def _LoadIdlAPI(self, api):
+      idl = idl_parser.IDLParser().ParseData(api)
+      return HandlebarDictGenerator(idl_schema.IDLSchema(idl).process()[0])
 
-  def _LoadPermissions(self, perms_json):
-    return json.loads(json_comment_eater.Nom(perms_json))
+  def __init__(self,
+               permissions_cache,
+               json_cache,
+               idl_cache,
+               base_path,
+               samples):
+    self._base_path = base_path
+    self._permissions_cache = permissions_cache
+    self._json_cache = json_cache
+    self._idl_cache = idl_cache
+    self._samples = samples
 
   def _GetFeature(self, path):
     # Remove 'experimental_' from path name to match the keys in
@@ -49,11 +67,17 @@ class APIDataSource(object):
     except Exception:
       return None
 
-  def _AddPermissionsDict(self, api_dict, path):
+  def _GenerateHandlebarContext(self, api_name, handlebar, path):
     return_dict = { 'permissions': self._GetFeature(path) }
-    return_dict.update(api_dict)
+    return_dict.update(handlebar.Generate(
+        self._FilterSamples(api_name, self._samples.values())))
     return return_dict
 
+  def _FilterSamples(self, api_name, samples):
+    api_search = '.' + api_name + '.'
+    return [sample for sample in samples
+            if any(api_search in api['name'] for api in sample['api_calls'])]
+
   def __getitem__(self, key):
     return self.get(key)
 
@@ -63,12 +87,13 @@ class APIDataSource(object):
     json_path = unix_name + '.json'
     idl_path = unix_name + '.idl'
     try:
-      return self._AddPermissionsDict(self._json_cache.GetFromFile(
-          self._base_path + '/' + json_path), path)
-    except Exception:
+      return self._GenerateHandlebarContext(key,
+          self._json_cache.GetFromFile(self._base_path + '/' + json_path),
+          path)
+    except OSError:
       try:
-        return self._AddPermissionsDict(self._idl_cache.GetFromFile(
-            self._base_path + '/' + idl_path), path)
-      except Exception as e:
-        logging.warn(e)
+        return self._GenerateHandlebarContext(key,
+            self._idl_cache.GetFromFile(self._base_path + '/' + idl_path),
+            path)
+      except OSError as e:
         raise

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

@@ -11,6 +11,10 @@ from file_system_cache import FileSystemCache
 from local_file_system import LocalFileSystem
 from api_data_source import APIDataSource
 
+class FakeSamplesDataSource:
+  def Create(self, request):
+    return {}
+
 class APIDataSourceTest(unittest.TestCase):
   def setUp(self):
     self._base_path = os.path.join('test_data', 'test_json')
@@ -21,11 +25,14 @@ class APIDataSourceTest(unittest.TestCase):
 
   def testSimple(self):
     cache_builder = FileSystemCache.Builder(LocalFileSystem(self._base_path))
-    data_source = APIDataSource(cache_builder, './')
+    data_source_factory = APIDataSource.Factory(cache_builder,
+                                                './',
+                                                FakeSamplesDataSource())
+    data_source = data_source_factory.Create({})
 
     # Take the dict out of the list.
     expected = json.loads(self._ReadLocalFile('expected_test_file.json'))
-    expected.update({ 'permissions': None })
+    expected['permissions'] = None
     self.assertEqual(expected, data_source['test_file'])
     self.assertEqual(expected, data_source['testFile'])
     self.assertEqual(expected, data_source['testFile.html'])

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

@@ -67,14 +67,15 @@ class HandlebarDictGenerator(object):
           { 'href': ref_dict['href'], 'text': ref_dict['text'], 'rest': rest })
     return ''.join(formatted_description)
 
-  def Generate(self):
+  def Generate(self, samples):
     try:
       return {
         'name': self._namespace.name,
         'types': map(self._GenerateType, self._namespace.types.values()),
         'functions': self._GenerateFunctions(self._namespace.functions),
         'events': map(self._GenerateEvent, self._namespace.events.values()),
-        'properties': self._GenerateProperties(self._namespace.properties)
+        'properties': self._GenerateProperties(self._namespace.properties),
+        'samples': samples,
       }
     except Exception as e:
       logging.error(e)

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

@@ -35,7 +35,7 @@ class DictGeneratorTest(unittest.TestCase):
   def _GenerateTest(self, filename):
     expected_json = json.loads(self._ReadLocalFile('expected_' + filename))
     gen = HandlebarDictGenerator(self._LoadJSON(filename))
-    self.assertEquals(expected_json, gen.Generate())
+    self.assertEquals(expected_json, gen.Generate([]))
 
   def testGenerate(self):
     self._GenerateTest('test_file.json')
@@ -57,7 +57,7 @@ class DictGeneratorTest(unittest.TestCase):
     self.assertEquals('234,567', _FormatValue(234567))
 
   def testFormatDescription(self):
-    dict_ = HandlebarDictGenerator(self._LoadJSON('ref_test.json')).Generate()
+    dict_ = HandlebarDictGenerator(self._LoadJSON('ref_test.json')).Generate([])
     self.assertEquals(_MakeLink('#type-type2', 'type2'),
                       _GetType(dict_, 'type1')['description'])
     self.assertEquals(

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

@@ -68,7 +68,6 @@ def _GetInstanceForBranch(branch, local_path):
                                      AppEngineMemcache(branch))
 
   cache_builder = FileSystemCache.Builder(file_system)
-  api_data_source = APIDataSource(cache_builder, API_PATH)
   api_list_data_source = APIListDataSource(cache_builder,
                                            file_system,
                                            API_PATH,
@@ -79,9 +78,12 @@ def _GetInstanceForBranch(branch, local_path):
                                                           file_system,
                                                           cache_builder,
                                                           EXAMPLES_PATH)
+  api_data_source_factory = APIDataSource.Factory(cache_builder,
+                                                  API_PATH,
+                                                  samples_data_source_factory)
   template_data_source_factory = TemplateDataSource.Factory(
       branch,
-      api_data_source,
+      api_data_source_factory,
       api_list_data_source,
       intro_data_source,
       samples_data_source_factory,

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

@@ -111,6 +111,12 @@ class SamplesDataSource(object):
     self._samples_path = samples_path
     self._request = request
 
+  def GetSamplesForAPI(self, api_name):
+    samples = self.values()
+    api_search = '.' + api_name + '.'
+    return [sample for sample in samples
+            if any(api_search in api['name'] for api in sample['api_calls'])]
+
   def _GetAcceptedLanguages(self):
     accept_language = self._request.headers.get('Accept-Language', None)
     if accept_language is None:
@@ -121,6 +127,9 @@ class SamplesDataSource(object):
   def __getitem__(self, key):
     return self.get(key)
 
+  def values(self):
+    return self.get('')
+
   def get(self, key):
     samples_list = self._cache.GetFromFileListing(self._samples_path + '/')
     return_list = []

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

@@ -39,7 +39,7 @@ class TemplateDataSource(object):
     """
     def __init__(self,
                  branch,
-                 api_data_source,
+                 api_data_source_factory,
                  api_list_data_source,
                  intro_data_source,
                  samples_data_source_factory,
@@ -49,7 +49,7 @@ class TemplateDataSource(object):
       self._branch_info = _MakeBranchDict(branch)
       self._static_resources = ((('/' + branch) if branch != 'local' else '') +
                                 '/static')
-      self._api_data_source = api_data_source
+      self._api_data_source_factory = api_data_source_factory
       self._api_list_data_source = api_list_data_source
       self._intro_data_source = intro_data_source
       self._samples_data_source_factory = samples_data_source_factory
@@ -60,16 +60,17 @@ class TemplateDataSource(object):
     def Create(self, request):
       """Returns a new TemplateDataSource bound to |request|.
       """
-      return TemplateDataSource(self._branch_info,
-                                self._static_resources,
-                                self._api_data_source,
-                                self._api_list_data_source,
-                                self._intro_data_source,
-                                self._samples_data_source_factory,
-                                self._cache,
-                                self._public_template_path,
-                                self._private_template_path,
-                                request)
+      return TemplateDataSource(
+          self._branch_info,
+          self._static_resources,
+          self._api_data_source_factory.Create(request),
+          self._api_list_data_source,
+          self._intro_data_source,
+          self._samples_data_source_factory.Create(request),
+          self._cache,
+          self._public_template_path,
+          self._private_template_path,
+          request)
 
   def __init__(self,
                branch_info,
@@ -77,17 +78,17 @@ class TemplateDataSource(object):
                api_data_source,
                api_list_data_source,
                intro_data_source,
-               samples_data_source_factory,
+               samples_data_source,
                cache,
                public_template_path,
                private_template_path,
                request):
     self._branch_info = branch_info
     self._static_resources = static_resources
-    self._api_data_source = api_data_source
     self._api_list_data_source = api_list_data_source
     self._intro_data_source = intro_data_source
-    self._samples_data_source = samples_data_source_factory.Create(request)
+    self._samples_data_source = samples_data_source
+    self._api_data_source = api_data_source
     self._cache = cache
     self._public_template_path = public_template_path
     self._private_template_path = private_template_path

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

@@ -15,6 +15,13 @@ from third_party.handlebar import Handlebar
 class _FakeRequest(object):
     pass
 
+class _FakeApiDataSourceFactory(object):
+  def __init__(self, input_dict):
+    self._input_dict = input_dict
+
+  def Create(self, samples):
+    return self._input_dict
+
 class _FakeSamplesDataSource(object):
   def Create(self, request):
     return {}
@@ -22,7 +29,7 @@ class _FakeSamplesDataSource(object):
 class TemplateDataSourceTest(unittest.TestCase):
   def setUp(self):
     self._base_path = os.path.join('test_data', 'template_data_source')
-    self._fake_api_data_source = {}
+    self._fake_api_data_source_factory = _FakeApiDataSourceFactory({})
     self._fake_api_list_data_source = {}
     self._fake_intro_data_source = {}
     self._fake_samples_data_source = _FakeSamplesDataSource()
@@ -40,7 +47,7 @@ class TemplateDataSourceTest(unittest.TestCase):
 
   def _CreateTemplateDataSource(self, input_dict, cache_builder):
     return (TemplateDataSource.Factory('fake_branch',
-                                       input_dict,
+                                       _FakeApiDataSourceFactory(input_dict),
                                        self._fake_api_list_data_source,
                                        self._fake_intro_data_source,
                                        self._fake_samples_data_source,
@@ -53,8 +60,8 @@ class TemplateDataSourceTest(unittest.TestCase):
     self._base_path = os.path.join(self._base_path, 'simple')
     fetcher = LocalFileSystem(self._base_path)
     cache_builder = FileSystemCache.Builder(fetcher)
-    t_data_source = self._CreateTemplateDataSource(self._fake_api_data_source,
-                                                    cache_builder)
+    t_data_source = self._CreateTemplateDataSource(
+        self._fake_api_data_source_factory, cache_builder)
     template_a1 = Handlebar(self._ReadLocalFile('test1.html'))
     self.assertEqual(template_a1.render({}, {'templates': {}}).text,
         t_data_source['test1'].render({}, {'templates': {}}).text)
@@ -69,8 +76,8 @@ class TemplateDataSourceTest(unittest.TestCase):
     self._base_path = os.path.join(self._base_path, 'partials')
     fetcher = LocalFileSystem(self._base_path)
     cache_builder = FileSystemCache.Builder(fetcher)
-    t_data_source = self._CreateTemplateDataSource(self._fake_api_data_source,
-                                                    cache_builder)
+    t_data_source = self._CreateTemplateDataSource(
+        self._fake_api_data_source_factory, cache_builder)
     self.assertEqual(
         self._ReadLocalFile('test_expected.html'),
         t_data_source['test_tmpl'].render(

chrome/common/extensions/docs/server2/templates/private/api_reference.html

@@ -26,3 +26,9 @@
     {{/}}
   {{/api.events}}
 </div>
+<a name="samples"></a>
+{{?api.samples}}<h2>Sample extensions that use chrome.{{api.name}}</h2>{{/}}
+{{#api.samples}}
+  <a name="sample-{{?prefix}}{{prefix}}-{{/}}{{name}}"></a>
+  <li><b><a href="{{path}}.zip">{{name}}</a></b> &ndash; {{description}}</li>
+{{/}}

chrome/common/extensions/docs/server2/templates/private/table_of_contents.html

@@ -20,6 +20,7 @@
           {{?api.properties}}<li>{{+partials.toc_properties}}</li>{{/}}
           {{?api.functions}}<li>{{+partials.toc_functions}}</li>{{/}}
           {{?api.events}}<li>{{+partials.toc_events}}</li>{{/}}
+          {{?api.samples}}<li>{{+partials.toc_samples}}</li>{{/}}
         {{/api}}
       </ol>
     </li>

chrome/common/extensions/docs/server2/templates/private/toc_samples.html

+<a href="#{{?prefix}}{{prefix}}-{{/}}samples">Sample Extensions</a>

chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json

@@ -101,8 +101,8 @@
       "description": "Gets stuff."
     }
   ],
-  "properties": [],
   "name": "tester",
+  "properties": [],
   "types": [
     {
       "functions": [],
@@ -159,5 +159,6 @@
       ],
       "description": "A cool event."
     }
-  ]
+  ],
+  "samples": []
 }