From 9a4c2c681f165cc1f7afd2c677943f43894915cb Mon Sep 17 00:00:00 2001 From: Devon Carew Date: Tue, 5 Apr 2016 12:33:12 -0700 Subject: [PATCH] add a dev/dartdoc.dart script to generate docs for the packages/ packages * add a dev/dartdoc.dart script to generate docs for the packages/ packages * remove description * rename readme * change to using --include-external * move docs to dev/docs --- dev/dartdoc.dart | 102 ++++++++++++++++++ dev/docs/.analysis_options | 3 + dev/docs/.gitignore | 8 ++ dev/docs/README.md | 6 ++ dev/docs/analytics.html | 9 ++ dev/docs/styles.html | 49 +++++++++ dev/profile_startup.dart | 2 +- doc/_analytics.html | 1 - .../lib/flutter_markdown.dart | 1 + .../lib/flutter_markdown_raw.dart | 2 +- packages/flutter_tools/pubspec.yaml | 4 + packages/flx/pubspec.yaml | 4 + 12 files changed, 188 insertions(+), 3 deletions(-) create mode 100755 dev/dartdoc.dart create mode 100644 dev/docs/.analysis_options create mode 100644 dev/docs/.gitignore create mode 100644 dev/docs/README.md create mode 100644 dev/docs/analytics.html create mode 100644 dev/docs/styles.html diff --git a/dev/dartdoc.dart b/dev/dartdoc.dart new file mode 100755 index 0000000000..54df99bf7c --- /dev/null +++ b/dev/dartdoc.dart @@ -0,0 +1,102 @@ +#!/usr/bin/env dart + +// Copyright 2016 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 'dart:async'; +import 'dart:convert'; +import 'dart:io'; + +/// This script expects to run with the cwd as the root of the flutter repo. It +/// will generate documentation for the packages in `packages/`, and leave the +/// documentation in `dev/docs/doc/api/`. +main(List args) async { + // Create the pubspec.yaml file. + StringBuffer buf = new StringBuffer(''' +name: Flutter +dependencies: +'''); + for (String package in _findPackageNames()) { + buf.writeln(' $package:'); + buf.writeln(' path: ../../packages/$package'); + } + new File('dev/docs/pubspec.yaml').writeAsStringSync(buf.toString()); + + // Create the library file. + Directory libDir = new Directory('dev/docs/lib'); + libDir.createSync(); + + StringBuffer contents = new StringBuffer('library temp_doc;\n\n'); + for (String libraryRef in _libraryRefs()) { + contents.writeln('import \'package:$libraryRef\';'); + } + new File('dev/docs/lib/temp_doc.dart').writeAsStringSync(contents.toString()); + + // Run pub. + Process process = await Process.start('pub', ['get'], workingDirectory: 'dev/docs'); + _print(process.stdout); + _print(process.stderr); + int code = await process.exitCode; + if (code != 0) + exit(code); + + // Generate the documentation; we require dartdoc >= 0.9.3+1. + List args = [ + 'global', 'run', 'dartdoc', + '--header', 'styles.html', + '--header', 'analytics.html', + '--dart-sdk', '../../bin/cache/dart-sdk', + '--exclude', 'temp_doc' + ]; + for (String libraryRef in _libraryRefs()) { + String name = _entityName(libraryRef); + + args.add('--include-external'); + args.add(name.substring(0, name.length - 5)); + } + + process = await Process.start('pub', args, workingDirectory: 'dev/docs'); + _print(process.stdout); + _print(process.stderr); + exit(await process.exitCode); +} + +List _findPackageNames() { + return _findPackages().map((Directory dir) => _entityName(dir.path)).toList(); +} + +List _findPackages() { + return new Directory('packages') + .listSync() + .where((FileSystemEntity entity) => entity is Directory) + .where((Directory dir) { + File pubspec = new File('${dir.path}/pubspec.yaml'); + bool nodoc = pubspec.readAsStringSync().contains('nodoc: true'); + return !nodoc; + }) + .toList(); + +} + +List _libraryRefs() sync* { + for (Directory dir in _findPackages()) { + String dirName = _entityName(dir.path); + + for (FileSystemEntity file in new Directory('${dir.path}/lib').listSync()) { + if (file is File && file.path.endsWith('.dart')) + yield '$dirName/${_entityName(file.path)}'; + } + } +} + +String _entityName(String path) { + return path.indexOf('/') == -1 ? path : path.substring(path.lastIndexOf('/') + 1); +} + +void _print(Stream> stream) { + stream + .transform(UTF8.decoder) + .transform(const LineSplitter()) + .listen(print); +} diff --git a/dev/docs/.analysis_options b/dev/docs/.analysis_options new file mode 100644 index 0000000000..8e12348b5c --- /dev/null +++ b/dev/docs/.analysis_options @@ -0,0 +1,3 @@ +analyzer: + exclude: + - 'lib/**' diff --git a/dev/docs/.gitignore b/dev/docs/.gitignore new file mode 100644 index 0000000000..2744c6bd2d --- /dev/null +++ b/dev/docs/.gitignore @@ -0,0 +1,8 @@ +.pub/ +packages +.packages +pubspec.lock + +pubspec.yaml +api/ +lib/ diff --git a/dev/docs/README.md b/dev/docs/README.md new file mode 100644 index 0000000000..d24d953d7c --- /dev/null +++ b/dev/docs/README.md @@ -0,0 +1,6 @@ +Flutter is a new way to build high-performance, cross-platform mobile apps. +Flutter is optimized for today's, and tomorrow's, mobile devices. We are focused +on low-latency input and high frame rates on Android and iOS. + +See the [getting started guide](https://flutter.io/getting-started/) for +information about using Flutter. diff --git a/dev/docs/analytics.html b/dev/docs/analytics.html new file mode 100644 index 0000000000..c3c1f30dae --- /dev/null +++ b/dev/docs/analytics.html @@ -0,0 +1,9 @@ + diff --git a/dev/docs/styles.html b/dev/docs/styles.html new file mode 100644 index 0000000000..02b90c1653 --- /dev/null +++ b/dev/docs/styles.html @@ -0,0 +1,49 @@ + + + + + + diff --git a/dev/profile_startup.dart b/dev/profile_startup.dart index f905795623..26bf728ebd 100755 --- a/dev/profile_startup.dart +++ b/dev/profile_startup.dart @@ -3,9 +3,9 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -import 'dart:io'; import 'dart:async'; import 'dart:convert'; +import 'dart:io'; const int ITERATIONS = 5; diff --git a/doc/_analytics.html b/doc/_analytics.html index fc5c2396a4..c3c1f30dae 100644 --- a/doc/_analytics.html +++ b/doc/_analytics.html @@ -6,5 +6,4 @@ ga('create', 'UA-67589403-2', 'auto'); ga('send', 'pageview'); - diff --git a/packages/flutter_markdown/lib/flutter_markdown.dart b/packages/flutter_markdown/lib/flutter_markdown.dart index 736e84f2db..d65c9a5508 100644 --- a/packages/flutter_markdown/lib/flutter_markdown.dart +++ b/packages/flutter_markdown/lib/flutter_markdown.dart @@ -2,6 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. +/// A library to render markdown formatted text. library flutter_markdown; export 'src/markdown.dart'; diff --git a/packages/flutter_markdown/lib/flutter_markdown_raw.dart b/packages/flutter_markdown/lib/flutter_markdown_raw.dart index d7fed2c666..3d2be6a5f0 100644 --- a/packages/flutter_markdown/lib/flutter_markdown_raw.dart +++ b/packages/flutter_markdown/lib/flutter_markdown_raw.dart @@ -2,7 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -library flutter_markdown; +library flutter_markdown_raw; export 'src/markdown_raw.dart'; export 'src/markdown_style_raw.dart'; diff --git a/packages/flutter_tools/pubspec.yaml b/packages/flutter_tools/pubspec.yaml index 80bae9e166..cb83e6e19f 100644 --- a/packages/flutter_tools/pubspec.yaml +++ b/packages/flutter_tools/pubspec.yaml @@ -41,3 +41,7 @@ dependencies: dev_dependencies: mockito: ^0.11.0 + +# Exclude this package from the hosted API docs. +dartdoc: + nodoc: true diff --git a/packages/flx/pubspec.yaml b/packages/flx/pubspec.yaml index 5cf07be1b6..55aa532704 100644 --- a/packages/flx/pubspec.yaml +++ b/packages/flx/pubspec.yaml @@ -16,3 +16,7 @@ dev_dependencies: flutter_tools: path: ../flutter_tools test: any # constrained by the dependency in flutter_tools + +# Exclude this package from the hosted API docs. +dartdoc: + nodoc: true