Extensions Docs Server: Proper $ref handling

chrome/common/extensions/docs/server2/handlebar_dict_generator.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 copy
 import logging
 import os
 
 import third_party.json_schema_compiler.model as model
 
 def _RemoveNoDocs(item):
   if type(item) == dict:
     if item.get('nodoc', False):
       return True
     for key, value in item.items():
       if _RemoveNoDocs(value):
         del item[key]
   elif type(item) == list:
     for i in item:
       if _RemoveNoDocs(i):
         item.remove(i)
   return False
 
 def _GetLinkToRefType(namespace_name, ref_type):
-  terms = ref_type.split('.')
-  if len(terms) > 1:
-    text = '.'.join(terms[1:])
-    href = terms[0] + '.html' + '#type-' + text
-  else:
-    href = namespace_name + '.html' + '#type-' +ref_type
-    text = ref_type
-  return ({
-    "href": href,
-    "text": text
-  })
+  if ref_type.startswith(namespace_name + '.'):
+    type_name = ref_type[namespace_name + '.':]

[not at google - send to devlin, 2012/07/26 03:12:27]

is this supposed to be len(namespace_name + '.') ?

[cduvall, 2012/07/26 17:57:44]

Done.

+    return { 'href': '#type-' + type_name, 'text': type_name }
+  elif '.' not in ref_type:
+    return { 'href': '#type-' + ref_type, 'text': ref_type }
+  api, type_name = ref_type.rsplit('.', 1)
+  return { 'href': api + '.html#type-' + type_name, 'text': ref_type }
 
 def _FormatValue(value):
   """Inserts commas every three digits for integer values. It is magic.
   """
   s = str(value)
   return ','.join([s[max(0, i - 3):i] for i in range(len(s), 0, -3)][::-1])
 
 class HandlebarDictGenerator(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):
     clean_json = copy.deepcopy(json)
     _RemoveNoDocs(clean_json)
     try:
       self._namespace = model.Namespace(clean_json, clean_json['namespace'])
     except Exception as e:
       logging.info(e)
 
+  def _StripPrefix(self, name):
+    if name.startswith(self._namespace.name + '.'):
+      return name[len(self._namespace.name + '.'):]
+    return name
+
+  def _ReplaceRefsInDescription(self, description):

[not at google - send to devlin, 2012/07/26 03:12:27]

function needs -2 indentation

[cduvall, 2012/07/26 17:57:44]

Done.

+      if description is None or '$ref:' not in description:
+        return description
+      refs = description.split('$ref:')

[not at google - send to devlin, 2012/07/26 03:12:27]

This is awesome. We should convert all those
chrome.{extension,runtime}.lastError references to be
$ref:chrome.runtime.lastError in all the docs.

Note that it looks like the current documentation system doesn't do this, so,
this is super useful.

[cduvall, 2012/07/26 17:57:44]

I shouldn't do this now because it will break the old docs right?

[not at google - send to devlin, 2012/07/30 08:04:34]

Actually it looks like it _does_ deal with $ref:

http://src.chromium.org/svn/trunk/src/chrome/common/extensions/docs/js/api_pa...
(search for $ref, about 2/3 of the way down).

So yeah, you could do that for lastError. Though in a follow up (and check that
it doesn't break the existing docs).

+      formatted_description = refs[0]
+      for ref in refs[1:]:

[not at google - send to devlin, 2012/07/26 03:12:27]

I don't think this algorithm works if the description starts with "$ref:".

[cduvall, 2012/07/26 17:57:44]

I think it does:

'$ref:Reffy is cool'.split('$ref:')
['', 'Reffy is cool']

+        ref, rest = ref.split(' ', 1)
+        ref_dict = _GetLinkToRefType(self._namespace.name, ref)
+        formatted_description += ('<a href="' + ref_dict['href'] + '">' +
+            ref_dict['text'] + '</a> ' + rest)

[not at google - send to devlin, 2012/07/26 03:12:27]

use a format string?

also, tip: += is inefficient in python. You should form an array of parts then
use return ''.join(formatted_description) at the end.

[cduvall, 2012/07/26 17:57:44]

Done.

+      return formatted_description
+
   def Generate(self):
     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)
       }
     except Exception as e:
       logging.info(e)
 
   def _GenerateType(self, type_):
     type_dict = {
-      'name': type_.name,
+      'name': self._StripPrefix(type_.name),
       'description': type_.description,

[not at google - send to devlin, 2012/07/26 03:12:27]

run *all* descriptions of through ReplaceRefsInDescription? Perhaps call it
FormatDescription?

[cduvall, 2012/07/26 17:57:44]

Done.

       'properties': self._GenerateProperties(type_.properties),
       'functions': self._GenerateFunctions(type_.functions),
       'events': map(self._GenerateEvent, type_.events.values())
     }
     self._RenderTypeInformation(type_, type_dict)
     return type_dict
 
   def _GenerateFunctions(self, functions):
     return map(self._GenerateFunction, functions.values())
 
@@ skipping 10 matching lines @@
     for param in function.params:
       function_dict['parameters'].append(self._GenerateProperty(param))
     if function_dict['callback']:
       function_dict['parameters'].append(function_dict['callback'])
     if len(function_dict['parameters']) > 0:
       function_dict['parameters'][-1]['last'] = True
     return function_dict
 
   def _GenerateEvent(self, event):
     event_dict = {
-      'name': event.name,
+      'name': self._StripPrefix(event.name),
       'description': event.description,
       'parameters': map(self._GenerateProperty, event.params)
     }
     if len(event_dict['parameters']) > 0:
       event_dict['parameters'][-1]['last'] = True
     return event_dict
 
   def _GenerateCallback(self, callback):
     if not callback:
       return None
     callback_dict = {
       'name': 'callback',
       'description': callback.description,
       'simple_type': {'simple_type': 'function'},
       'optional': callback.optional,
       'parameters': []
     }
     for param in callback.params:
       callback_dict['parameters'].append(self._GenerateProperty(param))
     if (len(callback_dict['parameters']) > 0):
       callback_dict['parameters'][-1]['last'] = True
     return callback_dict
 
   def _GenerateProperties(self, properties):
     return map(self._GenerateProperty, properties.values())
 
   def _GenerateProperty(self, property_):
     property_dict = {
-      'name': property_.name,
+      'name': self._StripPrefix(property_.name),
       'optional': property_.optional,
-      'description': property_.description,
+      'description': self._ReplaceRefsInDescription(property_.description),
       'properties': self._GenerateProperties(property_.properties),
       'functions': self._GenerateFunctions(property_.functions)
     }
     if property_.has_value:
       if isinstance(property_.value, int):
         property_dict['value'] = _FormatValue(property_.value)
       else:
         property_dict['value'] = property_.value
     else:
       self._RenderTypeInformation(property_, property_dict)
@@ skipping 17 matching lines @@
     elif property_.type_ == model.PropertyType.ENUM:
       dst_dict['enum_values'] = []
       for enum_value in property_.enum_values:
         dst_dict['enum_values'].append({'name': enum_value})
       if len(dst_dict['enum_values']) > 0:
         dst_dict['enum_values'][-1]['last'] = True
     elif property_.instance_of:
       dst_dict['simple_type'] = property_.instance_of.lower()
     else:
       dst_dict['simple_type'] = property_.type_.name.lower()