Dynamically generate a heading for Extension Docs API pages

tools/json_schema_compiler/idl_schema.py

 #! /usr/bin/env python
 # 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 itertools
 import json
 import os.path
 import re
 import sys
@@ skipping 290 matching lines @@
     return result
 
 
 class Namespace(object):
   '''
   Given an IDLNode representing an IDL namespace, converts into a Python
   dictionary that the JSON schema compiler expects to see.
   '''
 
   def __init__(self, namespace_node, nodoc=False, permissions=None,
-               internal=False):
+               internal=False, description=None, availability=None):

[not at google - send to devlin, 2013/04/04 05:19:23]

Sorry to bring this up at this late point, but I don't think we should have the
availability attached to the API definitions. We don't want to encourage people
to put them on JSON - we only need them for old APIs.

How about putting them in a separate description in
chrome/common/extensions/docs/templates/json/api_availability.json?

     self.namespace = namespace_node
     self.nodoc = nodoc
     self.internal = internal
     self.events = []
     self.functions = []
     self.types = []
     self.callbacks = OrderedDict()
     self.permissions = permissions or []
+    self.description = description
+    self.availability = availability
 
   def process(self):
     for node in self.namespace.children:
       if node.cls == 'Dictionary':
         self.types.append(Dictionary(node).process(self.callbacks))
       elif node.cls == 'Callback':
         k, v = Member(node).process(self.callbacks)
         self.callbacks[k] = v
       elif node.cls == 'Interface' and node.GetName() == 'Functions':
         self.functions = self.process_interface(node)
       elif node.cls == 'Interface' and node.GetName() == 'Events':
         self.events = self.process_interface(node)
       elif node.cls == 'Enum':
         self.types.append(Enum(node).process(self.callbacks))
       else:
         sys.exit('Did not process %s %s' % (node.cls, node))
     return {'namespace': self.namespace.GetName(),
+            'description': self.description,
+            'availability': self.availability,
             'nodoc': self.nodoc,
             'documentation_permissions_required': self.permissions,
             'types': self.types,
             'functions': self.functions,
             'internal': self.internal,
             'events': self.events}
 
   def process_interface(self, node):
     members = []
     for member in node.children:
       if member.cls == 'Member':
         name, properties = Member(member).process(self.callbacks)
         members.append(properties)
     return members
 
 class IDLSchema(object):
   '''
   Given a list of IDLNodes and IDLAttributes, converts into a Python list
   of api_defs that the JSON schema compiler expects to see.
   '''
 
   def __init__(self, idl):
     self.idl = idl
 
   def process(self):
     namespaces = []
     nodoc = False
     internal = False
     permissions = None
+    description = None
+    availability = None
     for node in self.idl:
       if node.cls == 'Namespace':
-        namespace = Namespace(node, nodoc, permissions, internal)
+        namespace = Namespace(node, nodoc, permissions, internal, description,
+                              availability)
         namespaces.append(namespace.process())
         nodoc = False
         internal = False
       elif node.cls == 'Copyright':
         continue
       elif node.cls == 'Comment':
-        continue
+        description = node.GetName()
+        if description == '':
+          description = None
       elif node.cls == 'ExtAttribute':
         if node.name == 'nodoc':
           nodoc = bool(node.value)
         elif node.name == 'permissions':
           permission = node.value.split(',')
         elif node.name == 'internal':
           internal = bool(node.value)
+        elif node.name == 'availability':
+          availability = node.value
         else:
           continue
       else:
         sys.exit('Did not process %s %s' % (node.cls, node))
     return namespaces
 
 def Load(filename):
   '''
   Given the filename of an IDL file, parses it and returns an equivalent
   Python dictionary in a format that the JSON schema compiler expects to see.
@@ skipping 11 matching lines @@
   '''
   Dump a json serialization of parse result for the IDL files whose names
   were passed in on the command line.
   '''
   for filename in sys.argv[1:]:
     schema = Load(filename)
     print json.dumps(schema, indent=2)
 
 if __name__ == '__main__':
   Main()