From 83ae4910596344012a298ce0b43b65d7de9c4bb4 Mon Sep 17 00:00:00 2001 From: "janicejl@google.com" Date: Fri, 16 Aug 2013 21:39:04 +0000 Subject: [PATCH] Appending working for library_list.json R=rnystrom@google.com Review URL: https://codereview.chromium.org//23003010 git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@26294 260f80e4-7a28-3924-810f-c04153c831b5 --- pkg/docgen/README.md | 8 +++--- pkg/docgen/bin/docgen.dart | 6 +++-- pkg/docgen/lib/docgen.dart | 50 ++++++++++++++++++++++++++------------ 3 files changed, 43 insertions(+), 21 deletions(-) diff --git a/pkg/docgen/README.md b/pkg/docgen/README.md index 24ba58a17f85..66d0a4639d7a 100644 --- a/pkg/docgen/README.md +++ b/pkg/docgen/README.md @@ -32,19 +32,21 @@ Run `dart docgen.dart [OPTIONS] ` - `-h`, `--help` Prints help and usage information. - `-v`, `--verbose` Output more logging information. -- `-j`, `--[no-]json` Outputs to JSON. Files are outputted to YAML by default. +- `-j`, `--[no-]json` Outputs to JSON. Files are outputted to YAML by default. +If `--append` is used, it takes the file-format of the previous run stated in +library_list.json ignoring the flag. - `--include-private` Flag to include private declarations. - `--include-sdk` Flag to parse SDK Library files imported. - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) - `--package-root` Sets the package root of the library being analyzed. -- `--append` Appends to the docs folder, library_list.txt, and index.txt. +- `--append` Appends to the docs folder, library_list.json, and index.txt. - `--introduction` Adds the provided markdown text file as the introduction for the outputted documentation. ###### Output Directory Documented libraries will be located at bin/docs in either YAML or JSON format -depending on options specified. There will also be a library_list.txt, +depending on options specified. There will also be a library_list.json, containing a list of all the libraries inside the docs folder. To get more information on how to use the outputted documentation with diff --git a/pkg/docgen/bin/docgen.dart b/pkg/docgen/bin/docgen.dart index ca4f78054cf2..293f3cf41640 100644 --- a/pkg/docgen/bin/docgen.dart +++ b/pkg/docgen/bin/docgen.dart @@ -49,7 +49,9 @@ ArgParser _initArgParser() { if (verbose) Logger.root.level = Level.FINEST; }); parser.addFlag('json', abbr: 'j', - help: 'Outputs to JSON. Files are outputted to YAML by default.', + help: 'Outputs to JSON. Files are outputted to YAML by default. ' + 'If --append is used, it takes the file-format of the previous ' + 'run stated in library_list.json ignoring the flag.', negatable: true); parser.addFlag('include-private', help: 'Flag to include private declarations.', negatable: false); @@ -61,7 +63,7 @@ ArgParser _initArgParser() { parser.addOption('package-root', help: 'Sets the package root of the library being analyzed.'); parser.addFlag('append', - help: 'Append to the docs folder, library_list.txt and index.txt', + help: 'Append to the docs folder, library_list.json and index.txt', defaultsTo: false, negatable: false); parser.addOption('introduction', help: 'Adds the provided markdown text file as the introduction' diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart index a51ab86d0ad8..6faca3f51322 100644 --- a/pkg/docgen/lib/docgen.dart +++ b/pkg/docgen/lib/docgen.dart @@ -244,26 +244,44 @@ void _documentLibraries(List libs, {bool includeSdk: false, if (parseSdk) entityMap['dart.core.Object'].subclasses.clear(); var filteredEntities = entityMap.values.where(_isVisible); + + // Outputs a JSON file with all libraries and their preview comments. + // This will help the viewer know what libraries are available to read in. + var libraryMap; + if (append) { + var docsDir = listDir('docs'); + if (!docsDir.contains('docs/library_list.json')) { + throw new StateError('No library_list.json'); + } + libraryMap = parse(new File('docs/library_list.json').readAsStringSync()); + libraryMap['libraries'].addAll(filteredEntities + .where((e) => e is Library) + .map((e) => e.previewMap)); + if (introduction.isNotEmpty) { + var intro = libraryMap['introduction']; + if (intro.isNotEmpty) intro += '

'; + intro += markdown.markdownToHtml( + new File(introduction).readAsStringSync(), + linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes); + libraryMap['introduction'] = intro; + } + outputToYaml = libraryMap['filetype'] == 'yaml'; + } else { + libraryMap = { + 'libraries' : filteredEntities.where((e) => + e is Library).map((e) => e.previewMap).toList(), + 'introduction' : introduction == '' ? + '' : markdown.markdownToHtml(new File(introduction) + .readAsStringSync(), linkResolver: linkResolver, + inlineSyntaxes: markdownSyntaxes), + 'filetype' : outputToYaml ? 'yaml' : 'json' + }; + } + _writeToFile(stringify(libraryMap), 'library_list.json'); // Output libraries and classes to file after all information is generated. filteredEntities.where((e) => e is Class || e is Library).forEach((output) { _writeIndexableToFile(output, outputToYaml); }); - // Outputs a YAML or JSON file with all libraries and their preview comments - // after creating all libraries. This will help the viewer know what - // libraries are available to read in. - var libraryMap = { - 'libraries' : filteredEntities.where((e) => - e is Library).map((e) => e.previewMap).toList(), - 'introduction' : introduction == '' ? - '' : markdown.markdownToHtml(new File(introduction).readAsStringSync(), - linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes) - }; - if (outputToYaml) { - _writeToFile(getYamlString(libraryMap), 'library_list.yaml', - append: append); - } else { - _writeToFile(stringify(libraryMap), 'library_list.json', append: append); - } // Outputs all the qualified names documented with their type. // This will help generate search results. _writeToFile(filteredEntities.map((e) =>