diff options
| author | mpcomplete@chromium.org <mpcomplete@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> | 2012-04-16 22:11:28 +0000 |
|---|---|---|
| committer | mpcomplete@chromium.org <mpcomplete@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> | 2012-04-16 22:11:28 +0000 |
| commit | d6bad8d5c7c2882f9ca62e70bef3d9ea60a10ca1 (patch) | |
| tree | eea521d18b304ace5eb9054000dfe6ec3c79d308 /chrome/common/extensions/docs/build | |
| parent | bf0fa4274346304e3ba8d8072e24038004c39ef3 (diff) | |
| download | chromium_src-d6bad8d5c7c2882f9ca62e70bef3d9ea60a10ca1.zip chromium_src-d6bad8d5c7c2882f9ca62e70bef3d9ea60a10ca1.tar.gz chromium_src-d6bad8d5c7c2882f9ca62e70bef3d9ea60a10ca1.tar.bz2 | |
Hack together a quick doc generator for IDL files.
- Changed the IDL parser to mine the Comment nodes, and process them for
parameter comments.
- Added hacks to the doc builder to parse the IDL files and spit out a
generated JSON file before running the generator.
BUG=no
TEST=no
Review URL: https://chromiumcodereview.appspot.com/10082038
git-svn-id: svn://svn.chromium.org/chrome/trunk/src@132474 0039d316-1c4b-4281-b951-d872f2087c98
Diffstat (limited to 'chrome/common/extensions/docs/build')
| -rwxr-xr-x | chrome/common/extensions/docs/build/build.py | 11 | ||||
| -rwxr-xr-x[-rw-r--r--] | chrome/common/extensions/docs/build/directory.py | 82 |
2 files changed, 77 insertions, 16 deletions
diff --git a/chrome/common/extensions/docs/build/build.py b/chrome/common/extensions/docs/build/build.py index 4f137a9..d08f1d1 100755 --- a/chrome/common/extensions/docs/build/build.py +++ b/chrome/common/extensions/docs/build/build.py @@ -27,6 +27,8 @@ _extension_api_dir = os.path.normpath(_base_dir + "/../api") _extension_api_json_schemas = glob.glob(_extension_api_dir + '/[a-zA-Z0-9]*.json') +_extension_api_idl_schemas = glob.glob(_extension_api_dir + + '/[a-zA-Z0-9]*.idl') _api_template_html = _template_dir + "/api_template.html" _page_shell_html = _template_dir + "/page_shell.html" _generator_html = _build_dir + "/generator.html" @@ -193,7 +195,8 @@ def main(): dump_render_tree = FindDumpRenderTree() # Load the manifest of existing API Methods - api_manifest = ApiManifest(_extension_api_json_schemas) + api_manifest = ApiManifest(_extension_api_json_schemas, + _extension_api_idl_schemas) # Read static file names static_names = GetStaticFileNames() @@ -212,6 +215,9 @@ def main(): raise Exception("--page-name argument must be one of %s." % ', '.join(sorted(page_names))) + # Write temporary JSON files based on the IDL inputs + api_manifest.generateJSONFromIDL() + # Render a manifest file containing metadata about all the extension samples samples_manifest = SamplesManifest(_samples_dir, _base_dir, api_manifest) samples_manifest.writeToFile(_samples_json) @@ -243,6 +249,9 @@ def main(): if (os.path.isfile(debug_log)): os.remove(debug_log) + # Cleanup our temporary IDL->JSON files + api_manifest.cleanupGeneratedFiles() + if 'EX_OK' in dir(os): return os.EX_OK else: diff --git a/chrome/common/extensions/docs/build/directory.py b/chrome/common/extensions/docs/build/directory.py index b11c56e..64f701c 100644..100755 --- a/chrome/common/extensions/docs/build/directory.py +++ b/chrome/common/extensions/docs/build/directory.py @@ -18,6 +18,14 @@ import json_minify as minify # default C locale. locale.setlocale(locale.LC_ALL, 'C') +import sys +_script_path = os.path.realpath(__file__) +_build_dir = os.path.dirname(_script_path) +_base_dir = os.path.normpath(_build_dir + "/..") +sys.path.insert(0, os.path.normpath(_base_dir + + "/../../../../tools/json_schema_compiler")) +import idl_schema + def sorted_walk(path): """ A version of os.walk that yields results in order sorted by name. @@ -58,18 +66,55 @@ def parse_json_file(path, encoding="utf-8"): return json_obj +def parse_idl_file(path): + """ Load the specified file and parse it as IDL. + + Args: + path: Path to a file containing JSON-encoded data. + """ + api_def = idl_schema.Load(path) + return api_def + +def write_json_to_file(manifest, path): + """ Writes the contents of this manifest file as a JSON-encoded text file. + + Args: + manifest: The manifest structure to write. + path: The path to write the manifest file to. + + Raises: + Exception: If the file could not be written. + """ + manifest_text = json.dumps(manifest, indent=2, + sort_keys=True, separators=(',', ': ')) + output_path = os.path.realpath(path) + try: + output_file = open(output_path, 'w') + except IOError, msg: + raise Exception("Failed to write the samples manifest file." + "The specific error was: %s." % msg) + output_file.write(manifest_text) + output_file.close() + class ApiManifest(object): """ Represents the list of API methods contained in the extension API JSON """ - def __init__(self, manifest_paths): - """ Read the supplied manifest file and parse its contents. + def __init__(self, json_paths, idl_paths): + """ Read the supplied json files and idl files and parse their contents. Args: - manifest_paths: Array of paths to API schemas. + json_paths: Array of paths to .json API schemas. + idl_paths: Array of paths to .idl API schemas. """ - self._manifest = []; - for path in manifest_paths: + self._manifest = [] + self._temporary_json_files = [] + for path in json_paths: self._manifest.extend(parse_json_file(path)) + for path in idl_paths: + module = parse_idl_file(path) + json_path = os.path.realpath(path.replace('.idl', '.json')) + self._temporary_json_files.append((module, json_path)) + self._manifest.extend(module) def _parseModuleDocLinksByKeyTypes(self, module, key): """ @@ -186,6 +231,22 @@ class ApiManifest(object): api_dict.update(self._parseModuleDocLinksByKeyTypes(module, 'events')) return api_dict + def generateJSONFromIDL(self): + """ Writes temporary .json files for every .idl file we have read, for + use by the documentation generator. + """ + for (module, json_path) in self._temporary_json_files: + if os.path.exists(json_path): + print ("WARNING: Overwriting existing file '%s'" + " with generated content." % (json_path)) + write_json_to_file(module, json_path) + + def cleanupGeneratedFiles(self): + """ Removes the temporary .json files we generated from .idl before. + """ + for (module, json_path) in self._temporary_json_files: + os.remove(json_path) + class SamplesManifest(object): """ Represents a manifest file containing information about the sample extensions available in the codebase. """ @@ -262,16 +323,7 @@ class SamplesManifest(object): Args: path: The path to write the samples manifest file to. """ - manifest_text = json.dumps(self._manifest_data, indent=2, - sort_keys=True, separators=(',', ': ')) - output_path = os.path.realpath(path) - try: - output_file = open(output_path, 'w') - except IOError, msg: - raise Exception("Failed to write the samples manifest file." - "The specific error was: %s." % msg) - output_file.write(manifest_text) - output_file.close() + write_json_to_file(self._manifest_data, path) def writeZippedSamples(self): """ For each sample in the current manifest, create a zip file with the |