dart-lang/sdk
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

pkg/docgen: removed yaml and append output support

Browse Source 
R=efortuna@google.com

Review URL: https://codereview.chromium.org//237443004

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@35039 260f80e4-7a28-3924-810f-c04153c831b5
This commit is contained in:
kevmoo@google.com
2014-04-14 20:56:15 +00:00
parent 96ef5a489c
commit 2c977913a4
5 changed files with 27 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/docgen/bin/docgen.dart
-10
View File
@@ -40,11 +40,9 @@ void main(List<String> arguments) {
docgen(files,
packageRoot: options['package-root'],
outputToYaml: !options['json'],
includePrivate: options['include-private'],
includeSdk: includeSdk,
parseSdk: options['parse-sdk'],
append: options['append'] && new Directory(options['out']).existsSync(),
introFileName: introduction,
out: options['out'],
excludeLibraries: excludedLibraries,
@@ -103,11 +101,6 @@ ArgParser _initArgParser() {
callback: (verbose) {
if (verbose) Logger.root.level = Level.FINEST;
});
parser.addFlag('json', abbr: 'j',
help: 'Outputs to JSON. If negated, outputs to YAML. '
'If --append is used, it takes the file-format of the previous '
'run stated in library_list.json, ignoring the flag.',
negatable: true, defaultsTo: true);
parser.addFlag('include-private',
help: 'Flag to include private declarations.', negatable: false);
parser.addFlag('include-sdk',
@@ -119,9 +112,6 @@ ArgParser _initArgParser() {
defaultsTo: false, negatable: false);
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.json and index.txt',
defaultsTo: false, negatable: false);
parser.addFlag('compile', help: 'Clone the documentation viewer repo locally '
'(if not already present) and compile with dart2js', defaultsTo: false,
negatable: false);
pkg/docgen/lib/docgen.dart
+3 -4
View File
@@ -38,8 +38,7 @@ export 'src/package_helpers.dart' show packageNameFor;
///
/// Returned Future completes with true if document generation is successful.
Future<bool> docgen(List<String> files, {String packageRoot,
bool outputToYaml: false, bool includePrivate: false,
bool includeSdk: false, bool parseSdk: false, bool append: false,
bool includePrivate: false, bool includeSdk: false, bool parseSdk: false,
String introFileName: '', String out: gen.DEFAULT_OUTPUT_DIRECTORY,
List<String> excludeLibraries: const [],
bool includeDependentPackages: false, bool compile: false,
@@ -49,8 +48,8 @@ Future<bool> docgen(List<String> files, {String packageRoot,
if (!noDocs) {
viewer.ensureMovedViewerCode();
result = gen.generateDocumentation(files, packageRoot: packageRoot,
outputToYaml: outputToYaml, includePrivate: includePrivate,
includeSdk: includeSdk, parseSdk: parseSdk, append: append,
includePrivate: includePrivate,
includeSdk: includeSdk, parseSdk: parseSdk,
introFileName: introFileName, out: out,
excludeLibraries: excludeLibraries,
includeDependentPackages: includeDependentPackages,
pkg/docgen/lib/src/dart2yaml.dart
-84
View File
@@ -1,84 +0,0 @@
// Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
/**
* This library is used to convert data from a map to a YAML string.
*/
library docgen.dart2yaml;
/**
* Gets a String representing the input Map in YAML format.
*/
String getYamlString(Map documentData) {
StringBuffer yaml = new StringBuffer();
_addLevel(yaml, documentData, 0);
return yaml.toString();
}
/**
* This recursive function builds a YAML string from [documentData] and
* adds it to [yaml].
* The [level] input determines the indentation of the block being processed.
* The [isList] input determines whether [documentData] is a member of an outer
* lists of maps. A map must be preceeded with a '-' if it is to exist at the
* same level of indentation in the YAML output as other members of the list.
*/
void _addLevel(StringBuffer yaml, Map documentData, int level,
{bool isList: false}) {
// The order of the keys could be nondeterministic, but it is insufficient
// to just sort the keys no matter what, as their order could be significant
// (i.e. parameters to a method). The order of the keys should be enforced
// by the caller of this function.
var keys = documentData.keys.toList();
keys.forEach((key) {
_calcSpaces(level, yaml);
// Only the first entry of the map should be preceeded with a '-' since
// the map is a member of an outer list and the map as a whole must be
// marked as a single member of that list. See example 2.4 at
// http://www.yaml.org/spec/1.2/spec.html#id2759963
if (isList && key == keys.first) {
yaml.write("- ");
level++;
}
yaml.write("\"$key\" : ");
if (documentData[key] is Map) {
yaml.write("\n");
_addLevel(yaml, documentData[key], level + 1);
} else if (documentData[key] is List) {
var elements = documentData[key];
yaml.write("\n");
elements.forEach( (element) {
if (element is Map) {
_addLevel(yaml, element, level + 1, isList: true);
} else {
_calcSpaces(level + 1, yaml);
yaml.write("- ${_processElement(element)}");
}
});
} else {
yaml.write(_processElement(documentData[key]));
}
});
}
/**
* Returns an escaped String form of the inputted element.
*/
String _processElement(var element) {
var contents = element.toString()
.replaceAll('\\', r'\\')
.replaceAll('"', r'\"')
.replaceAll('\n', r'\n');
return '"$contents"\n';
}
/**
* Based on the depth in the file, this function returns the correct spacing
* for an element in the YAML output.
*/
void _calcSpaces(int spaceLevel, StringBuffer yaml) {
for (int i = 0; i < spaceLevel; i++) {
yaml.write(" ");
}
}
pkg/docgen/lib/src/generator.dart
+23 -59
View File
@@ -24,7 +24,6 @@ import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mir
import '../../../../sdk/lib/_internal/compiler/implementation/source_file_provider.dart';
import '../../../../sdk/lib/_internal/libraries.dart';
import 'dart2yaml.dart';
import 'io.dart';
import 'library_helpers.dart';
import 'models.dart';
@@ -62,7 +61,7 @@ String _dartBinary;
/// Returned Future completes with true if document generation is successful.
Future<bool> generateDocumentation(List<String> files, {String packageRoot, bool
outputToYaml: true, bool includePrivate: false, bool includeSdk: false, bool
parseSdk: false, bool append: false, String introFileName: '', out:
parseSdk: false, String introFileName: '', out:
DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries: const [], bool
includeDependentPackages: false, String startPage, String dartBinary, String
pubScript}) {
@@ -72,7 +71,7 @@ Future<bool> generateDocumentation(List<String> files, {String packageRoot, bool
logger.onRecord.listen((record) => print(record.message));
_ensureOutputDirectory(out, append);
_ensureOutputDirectory(out);
var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files);
var requestedLibraries = _findLibrariesToDocument(files,
@@ -105,8 +104,7 @@ Future<bool> generateDocumentation(List<String> files, {String packageRoot, bool
librariesToDocument.removeWhere((x) => _excluded.contains(
dart2js_util.nameOf(x)));
_documentLibraries(librariesToDocument, includeSdk: includeSdk,
outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
introFileName: introFileName, startPage: startPage);
parseSdk: parseSdk, introFileName: introFileName, startPage: startPage);
return true;
});
}
@@ -134,7 +132,7 @@ Future<MirrorSystem> getMirrorSystem(List<Uri> libraries,
}
/// Writes [text] to a file in the output directory.
void _writeToFile(String text, String filename, {bool append: false}) {
void _writeToFile(String text, String filename) {
if (text == null) return;
Directory dir = new Directory(_outputDirectory);
if (!dir.existsSync()) {
@@ -154,7 +152,7 @@ void _writeToFile(String text, String filename, {bool append: false}) {
}
}
File file = new File(path.join(_outputDirectory, filename));
file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE);
file.writeAsStringSync(text, mode: FileMode.WRITE);
}
/// Resolve all the links in the introductory comments for a given library or
@@ -188,9 +186,8 @@ int _indexableComparer(Indexable a, Indexable b) {
}
/// Creates documentation for filtered libraries.
void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false, bool
outputToYaml: true, bool append: false, bool parseSdk: false, String
introFileName: '', String startPage}) {
void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
bool parseSdk: false, String introFileName: '', String startPage}) {
libs.forEach((lib) {
// Files belonging to the SDK have a uri that begins with 'dart:'.
if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
@@ -214,45 +211,26 @@ void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false, bool
// Outputs a JSON file with all libraries and their preview comments.
// This will help the viewer know what libraries are available to read in.
Map<String, dynamic> libraryMap;
if (append) {
var docsDir = listDir(_outputDirectory);
if (!docsDir.contains('$_outputDirectory/library_list.json')) {
throw new StateError('No library_list.json');
}
libraryMap = JSON.decode(new File('$_outputDirectory/library_list.json'
).readAsStringSync());
libraryMap['libraries'].addAll(filteredEntities.where((e) => e is Library
).map((e) => e.previewMap));
var intro = libraryMap['introduction'];
var spacing = intro.isEmpty ? '' : '<br/><br/>';
libraryMap['introduction'] =
"$intro$spacing${_readIntroductionFile(introFileName, includeSdk)}";
outputToYaml = libraryMap['filetype'] == 'yaml';
} else {
libraryMap = {
Map<String, dynamic> libraryMap = {
'libraries': filteredEntities.where((e) => e is Library).map((e) =>
e.previewMap).toList(),
'introduction': _readIntroductionFile(introFileName, includeSdk),
'filetype': outputToYaml ? 'yaml' : 'json'
'filetype': 'json'
};
}
_writeOutputFiles(libraryMap, filteredEntities, outputToYaml, append,
startPage);
_writeOutputFiles(libraryMap, filteredEntities, startPage);
}
/// Output all of the libraries and classes into json or yaml files for
/// consumption by a viewer.
/// Output all of the libraries and classes into json files for consumption by a
/// viewer.
void _writeOutputFiles(Map<String, dynamic> libraryMap, Iterable<Indexable>
filteredEntities, bool outputToYaml, bool append, String startPage) {
filteredEntities, String startPage) {
if (startPage != null) libraryMap['start-page'] = startPage;
_writeToFile(JSON.encode(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);
_writeIndexableToFile(output);
});
// Outputs all the qualified names documented with their type.
@@ -260,40 +238,26 @@ void _writeOutputFiles(Map<String, dynamic> libraryMap, Iterable<Indexable>
var sortedEntities = filteredEntities.map((e) =>
'${e.qualifiedName} ${e.typeName}').toList()..sort();
_writeToFile(sortedEntities.join('\n') + '\n', 'index.txt', append: append);
_writeToFile(sortedEntities.join('\n') + '\n', 'index.txt');
var index = new SplayTreeMap.fromIterable(filteredEntities,
key: (e) => e.qualifiedName, value: (e) => e.typeName);
if (append) {
var previousIndex = JSON.decode(new File('$_outputDirectory/index.json'
).readAsStringSync());
index.addAll(previousIndex);
}
_writeToFile(JSON.encode(index), 'index.json');
}
/// Helper method to serialize the given Indexable out to a file.
void _writeIndexableToFile(Indexable result, bool outputToYaml) {
var outputFile = result.fileName;
var output;
if (outputToYaml) {
output = getYamlString(result.toMap());
outputFile = outputFile + '.yaml';
} else {
output = JSON.encode(result.toMap());
outputFile = outputFile + '.json';
}
void _writeIndexableToFile(Indexable result) {
var outputFile = result.fileName + '.json';
var output = JSON.encode(result.toMap());
_writeToFile(output, outputFile);
}
/// Set the location of the ouput directory, and ensure that the location is
/// available on the file system.
void _ensureOutputDirectory(String outputDirectory, bool append) {
void _ensureOutputDirectory(String outputDirectory) {
_outputDirectory = outputDirectory;
if (!append) {
var dir = new Directory(_outputDirectory);
if (dir.existsSync()) dir.deleteSync(recursive: true);
}
var dir = new Directory(_outputDirectory);
if (dir.existsSync()) dir.deleteSync(recursive: true);
}
/// Analyzes set of libraries and provides a mirror system which can be used
@@ -326,8 +290,8 @@ Future<MirrorSystem> analyzeLibraries(List<Uri> libraries, String
///
/// If packageRoot is not explicitly passed, we examine the files we're
/// documenting to attempt to find a package root.
String _obtainPackageRoot(String packageRoot, bool parseSdk, List<String> files)
{
String _obtainPackageRoot(String packageRoot, bool parseSdk,
List<String> files) {
if (packageRoot == null && !parseSdk) {
var type = FileSystemEntity.typeSync(files.first);
if (type == FileSystemEntityType.DIRECTORY) {
utils/apidoc/docgen.gyp
+1 -2
View File
@@ -78,14 +78,13 @@
'--package-root=<(PRODUCT_DIR)/packages',
'../../pkg/docgen/bin/docgen.dart',
'--out=<(PRODUCT_DIR)/api_docs/docgen',
'--json',
'--include-sdk',
'--no-include-dependent-packages',
'--package-root=<(PRODUCT_DIR)/packages',
'--exclude-lib=async_helper',
'--exclude-lib=expect',
'--exclude-lib=docgen',
'../../pkg',
'../../pkg'
],
'message': 'Running docgen: <(_action)',
},