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

chrome/common/extensions/docs/server2/reference_resolver.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.
+
+from file_system import FileNotFoundError
+
+def _ClassifySchemaNode(node_name, api):
+  if '.' in node_name:
+    node_name, rest = node_name.split('.', 1)
+  else:
+    rest = None
+  for key, group in [('types', 'type'),
+                     ('functions', 'method'),
+                     ('events', 'event'),
+                     ('properties', 'property')]:
+    for item in api.get(key, []):
+      if item['name'] == node_name:
+        if rest is not None:
+          ret = _ClassifySchemaNode(rest, item)
+          if ret is not None:
+            return ret
+        else:
+          return group
+  return None
+
+class ReferenceResolver(object):
+  """Resolves references to $ref's by searching through the APIs to find the
+  correct node.
+  """
+  class Factory(object):
+    def __init__(self, api_data_source, api_list_data_source):
+      self._api_data_source = api_data_source
+      self._api_list_data_source = api_list_data_source
+
+    def Create(self):
+      return ReferenceResolver(self._api_data_source,
+                               self._api_list_data_source)
+
+  def __init__(self, api_data_source, api_list_data_source):
+    self._api_data_source = api_data_source
+    self._api_list_data_source = api_list_data_source
+
+  def GetLink(self, namespace_name, ref):
+    if ref.startswith('%s.' % namespace_name):
+      ref = ref[len('%s.' % namespace_name):]
+    if '.' not in ref:
+      try:
+        category = _ClassifySchemaNode(
+            ref,
+            self._api_data_source.get(namespace_name))
+      except FileNotFoundError:
+        return None
+      if category is None:
+        return None
+      return { 'href': '#%s-%s' % (category, ref), 'text': ref }
+    parts = ref.split('.')

[not at google - send to devlin, 2012/11/05 19:47:50]

It would be nice to write it in such a way that the two special cases above
weren't necessary.

Firstly there's nothing particularly wrong with generating an anchor to
"foo.html#blah" from within foo.html itself. It will be equivalent to "#blah".

And secondly perhaps the code below here can be written such that it works if
parts is a singleton list.

Anyway, no biggie if not.

[cduvall, 2012/11/06 00:58:54]

I ended up needing a special case for $refs not prefixed by the namespace name.
This allows it to handle things like $ref:StorageArea.get (in the storage API).
I can't think of a clean way to eliminate this special case.

+    api_list = self._api_list_data_source.GetAllNames()
+    for i, part in enumerate(parts):
+      if '.'.join(parts[:i]) not in api_list:
+        continue
+      try:
+        api_name = '.'.join(parts[:i])
+        api = self._api_data_source.get(api_name)
+      except FileNotFoundError:
+        continue
+      name = '.'.join(parts[i:])
+      category = _ClassifySchemaNode(name, api)
+      if category is None:
+        continue
+      return {
+        'href': '%s.html#%s-%s' % (api_name, category, name.replace('.', '-')),
+        'text': ref
+      }
+    return None