Extensions Docs Server: Generalize $ref's to work for any schema node

chrome/common/extensions/docs/server2/samples_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 hashlib
 import json
 import logging
 import re
 
 import compiled_file_system as compiled_fs
 from file_system import FileNotFoundError
+from reference_resolver import ReferenceResolver
 import third_party.json_schema_compiler.json_comment_eater as json_comment_eater
 import third_party.json_schema_compiler.model as model
 import url_constants
 
 DEFAULT_ICON_PATH = '/images/sample-default-icon.png'
 
-def _MakeAPILink(prefix, item, api_list):
-  item = item.replace('chrome.', '')
-  parts = item.split('.')
-  api_name = []
-  for i in range(1, len(parts) + 1):
-    if '.'.join(parts[:i]) in api_list:
-      return '%s.html#%s-%s' % ('.'.join(parts[:i]),
-                                prefix,
-                                '.'.join(parts[i:]))
-  return None
-
 class SamplesDataSource(object):
   """Constructs a list of samples and their respective files and api calls.
   """
 
   class Factory(object):
     """A factory to create SamplesDataSource instances bound to individual
     Requests.
     """
     def __init__(self,
                  channel,
                  file_system,
                  github_file_system,
                  cache_factory,
                  github_cache_factory,
+                 api_data_source_factory,
                  api_list_data_source_factory,
                  samples_path):
       self._file_system = file_system
       self._github_file_system = github_file_system
       self._static_path = ((('/' + channel) if channel != 'local' else '') +
                            '/static')
       self._extensions_cache = cache_factory.Create(self._MakeSamplesList,
                                                     compiled_fs.EXTENSIONS)
       self._apps_cache = github_cache_factory.Create(
           lambda x: self._MakeSamplesList(x, is_apps=True),
           compiled_fs.APPS)
-      self._api_list_data_source = api_list_data_source_factory.Create()
       self._samples_path = samples_path
+      self._reference_resolver = ReferenceResolver(
+          api_data_source_factory.Create(None,
+                                         self.Create(None),
+                                         resolve_refs=False),
+          api_list_data_source_factory.Create())

[not at google - send to devlin, 2012/11/02 17:26:48]

A good clue for when you need to introduce a Factory class for constructing a
dependency is if you need to pass through an argument (here
api_data_source_factory and api_list_data_source_factory) purely to satisfy the
dependency for constructing a different class.

I.e. it's ReferenceResolver.Factory time.

[cduvall, 2012/11/03 01:30:05]

Cool, thanks for the architecture tips they're super helpful.

 
     def Create(self, request):
       """Returns a new SamplesDataSource bound to |request|.
       """
       return SamplesDataSource(self._extensions_cache,
                                self._apps_cache,
                                self._samples_path,
                                request)
 
-    def _GetAllAPINames(self):
-      apis = []
-      for k1 in ['apps', 'extensions']:
-        for k2 in ['chrome', 'experimental']:
-          apis.extend(
-              [api['name'] for api in self._api_list_data_source[k1][k2]])
-      return apis
-
     def _GetAPIItems(self, js_file):
       return set(re.findall('(chrome\.[a-zA-Z0-9\.]+)', js_file))
 
     def _GetDataFromManifest(self, path, file_system):
       manifest = file_system.ReadSingle(path + '/manifest.json')
       try:
         manifest_json = json.loads(json_comment_eater.Nom(manifest))
       except ValueError as e:
         logging.error('Error parsing manifest.json for %s: %s' % (path, e))
         return None
@@ skipping 18 matching lines @@
         except ValueError as e:
           logging.error('Error parsing locales files for %s: %s' % (path, e))
         else:
           for path, json_ in locales_json:
             l10n_data['locales'][path[len(locales_path):].split('/')[0]] = json_
       return l10n_data
 
     def _MakeSamplesList(self, files, is_apps=False):
       file_system = self._github_file_system if is_apps else self._file_system
       samples_list = []
-      api_list = self._GetAllAPINames()
       for filename in sorted(files):
         if filename.rsplit('/')[-1] != 'manifest.json':
           continue
         # This is a little hacky, but it makes a sample page.
         sample_path = filename.rsplit('/', 1)[-2]
         sample_files = [path for path in files
                         if path.startswith(sample_path + '/')]
         js_files = [path for path in sample_files if path.endswith('.js')]
         try:
           js_contents = file_system.Read(js_files).Get()
         except FileNotFoundError as e:
           logging.warning('Error fetching samples files: %s. Was a file '
                           'deleted from a sample? This warning should go away '
                           'in 5 minutes.' % e)
           continue
         api_items = set()
         for js in js_contents.values():
           api_items.update(self._GetAPIItems(js))
 
         api_calls = []
         for item in api_items:
           if len(item.split('.')) < 3:
             continue
           if item.endswith('.removeListener') or item.endswith('.hasListener'):
             continue
           if item.endswith('.addListener'):
             item = item[:-len('.addListener')]
-            link = _MakeAPILink('event', item, api_list)
-            if link is None:
-              continue
-            api_calls.append({
-              'name': item,
-              'link': link
-            })
-          else:
-            # TODO(cduvall): this might be a property or a type.
-            link = _MakeAPILink('method', item, api_list)
-            if link is None:
-              continue
-            api_calls.append({
-              'name': item,
-              'link': link
-            })
+          if item.startswith('chrome.'):
+            item = item[len('chrome.'):]
+          ref_data = self._reference_resolver.GetLinkToRefType('samples', item)
+          if ref_data is None:
+            continue
+          api_calls.append({
+            'name': ref_data['text'],
+            'link': ref_data['href']
+          })
         try:
           manifest_data = self._GetDataFromManifest(sample_path, file_system)
         except FileNotFoundError as e:
           logging.warning('Error getting data from samples manifest: %s. If '
                           'this file was deleted from a sample this message '
                           'should go away in 5 minutes.' % e)
           continue
         if manifest_data is None:
           continue
 
@@ skipping 91 matching lines @@
     return return_list
 
   def __getitem__(self, key):
     return self.get(key)
 
   def get(self, key):
     return {
       'apps': lambda: self._CreateSamplesDict('apps'),
       'extensions': lambda: self._CreateSamplesDict('extensions')
     }.get(key, lambda: {})()