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

chrome/common/extensions/docs/server2/api_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 json
 import logging
 import os
 
 from handlebar_dict_generator import HandlebarDictGenerator
 import third_party.json_schema_compiler.json_comment_eater as json_comment_eater
 import third_party.json_schema_compiler.model as model
 import third_party.json_schema_compiler.idl_schema as idl_schema
 import third_party.json_schema_compiler.idl_parser as idl_parser
 
 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):
+
+  class Factory(object):
+    def __init__(self, cache_builder, base_path):
+      self._cache_builder = cache_builder
+      self._base_path = base_path
+
+    def Create(self, samples):
+      return APIDataSource(self._cache_builder, self._base_path, samples)
+
+  def __init__(self, cache_builder, base_path, samples):
+    self._samples = samples
     self._json_cache = cache_builder.build(self._LoadJsonAPI)
     self._idl_cache = cache_builder.build(self._LoadIdlAPI)

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

This means that on every construction (via the Factory) the caches will be
re-created. That kinda defeats the purpose of the caches, and it's one of the
reasons the Factory exists, so that the cache can be shared across all instances
of this.

Have a look at how template_data_source and samples_data_source work. Basically,
the Factory constructs and owns the caches, then passes a reference to the cache
in APIDataSource in its constructor, not its Builder.

That said, the samples are a dependency of HandlebarDictGenerator not this
class, so the injection of the samples should be done there not here.

I.e. the Factory should go on HandlebarDictGenerator
(HandlebarDictGenerator.Factory), and instead of creating a
HandlebarDictGenerator here directly, inject the HDG.Factory and use Create()
rather than the constructor below.

So:
1. add HandlebarDictGenerator.Factory; takes the samples in its constructor.
2. create it in echo_handler.py
3. when classes need to create HandlebarDictGenerators (e.g. this one), inject
it into its constructor.
4. Instead of HandlebarDictGenerator(schema), do
self._handlebar_dict_generator_factory.Create(schema).

[chebert, 2012/07/31 22:41:33]

The issue I am having with this is that the APIDataSource gets created long
before the samples_data_source is created. 

so basically the earliest place we could make the
handlebar_dict_generator_factory would be in the template_data_source, on its
creation, and immediately after, we would be passing the
handlebar_dict_generator to the api_data_source.

An issue I would then have with the first part, then would be that the
HandlebarDictGenerator is dependent on the samples, so the caches couldn't be
built until this point anyway.

On 2012/07/30 12:23:03, kalman wrote:

[not at google - send to devlin, 2012/08/01 10:09:19]

Ah sorry, looks like I confused myself, and you in the process. My apologies.

Yeah, HandlebarDictGenerator has a semantically different lifetime to the
DataSources:

The DataSource classes are scoped to requests, meaning that each will probably
need a Factory with a Create(request) method on it (for those that don't, it's
somewhat inevitable). Perhaps we should just go through and do that for all of
them to make it clearer.

HandlebarDictGenerator on the other hand is basically, itself, a factory-style
object for dicts to pass through to the Handlebar objects.
HandlebarDictGenerator is the Factory, .Generate() is like Create(), except
instead of returning classes it returns dicts.

However, I think this stuff will be easier to follow if we treat
HandlebarDictGenerator as just exposing data to Handlebar templates; so pass the
relevant data (e.g. the samples) into Generate.

I've written what I meant here: https://chromiumcodereview.appspot.com/10830115/

sorry about all this building-up-injection stuff, but once it's done, it's done.

     self._base_path = base_path
 
   def _LoadJsonAPI(self, api):
     generator = HandlebarDictGenerator(
-        json.loads(json_comment_eater.Nom(api))[0])
+        json.loads(json_comment_eater.Nom(api))[0],
+        self._samples)
     return generator.Generate()
 
   def _LoadIdlAPI(self, api):
     idl = idl_parser.IDLParser().ParseData(api)
-    generator = HandlebarDictGenerator(idl_schema.IDLSchema(idl).process()[0])
+    generator = HandlebarDictGenerator(idl_schema.IDLSchema(idl).process()[0],
+                                       self._samples)
     return generator.Generate()
 
   def __getitem__(self, key):
     return self.get(key)
 
   def get(self, key):
     path, ext = os.path.splitext(key)
     unix_name = model.UnixName(path)
     json_path = unix_name + '.json'
     idl_path = unix_name + '.idl'
     try:
       return self._json_cache.GetFromFile(self._base_path + '/' + json_path)
     except Exception:
       try:
         return self._idl_cache.GetFromFile(self._base_path + '/' + idl_path)
       except Exception as e:
         logging.warn(e)
         return None