| OLD | NEW |
|---|
| (Empty) |
| 1 #!/usr/bin/env python | |
| 2 # | |
| 3 # Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | |
| 4 # for details. All rights reserved. Use of this source code is governed by a | |
| 5 # BSD-style license that can be found in the LICENSE file. | |
| 6 | |
| 7 # Run this script to generate documentation for a directory and serve | |
| 8 # the results to localhost for viewing in the browser. | |
| 9 | |
| 10 import optparse | |
| 11 import os | |
| 12 from os.path import join, dirname, abspath, exists | |
| 13 import platform | |
| 14 import subprocess | |
| 15 import sys | |
| 16 sys.path.append(abspath(join(dirname(__file__), '../../../tools'))) | |
| 17 import utils | |
| 18 | |
| 19 DIRECTORY = abspath(dirname(__file__)) | |
| 20 DART_DIR = dirname(dirname(dirname(DIRECTORY))) | |
| 21 DART_EXECUTABLE = join(DART_DIR, | |
| 22 '%s/%s/dart-sdk/bin/dart' % (utils.BUILD_ROOT[utils.GuessOS()], | |
| 23 utils.GetBuildConf('release', utils.GuessArchitecture()))) | |
| 24 PUB = join(DART_DIR, 'sdk/bin/pub') | |
| 25 DART2JS = join(DART_DIR, 'sdk/bin/dart2js') | |
| 26 PACKAGE_ROOT = join(dirname(dirname(dirname(DART_EXECUTABLE[:-(len('dart'))]))), | |
| 27 'packages/') | |
| 28 EXCLUDED_PACKAGES = ['browser', 'mutation_observer', 'pkg.xcodeproj'] | |
| 29 APPSERVER_EXECUTABLE = 'dev_appserver.py' | |
| 30 | |
| 31 | |
| 32 def SetPackageRoot(path): | |
| 33 global PACKAGE_ROOT | |
| 34 if exists(path): | |
| 35 PACKAGE_ROOT = abspath(path) | |
| 36 | |
| 37 | |
| 38 def ParseArgs(): | |
| 39 parser = optparse.OptionParser(description='Generate documentation and ' | |
| 40 'display the resulting documentation in the browser.') | |
| 41 parser.add_option('--full-docs-only', '-d', dest='just_docs', | |
| 42 action='store_true', default=False, | |
| 43 help='Only generate documentation, no html output. (If no other ' | |
| 44 'options are specified, will document the SDK and all packages in the ' | |
| 45 'repository.)') | |
| 46 parser.add_option('--package-root', '-p', dest='pkg_root', | |
| 47 help='The package root for dart (default is in the build directory).', | |
| 48 action='store', default=PACKAGE_ROOT) | |
| 49 parser.add_option('--docgen-options', '-o', | |
| 50 dest='docgen_options', help='Options to pass to docgen. If no file to ' | |
| 51 'document is specified, by default we generate all documenation for the ' | |
| 52 'SDK and all packages in the dart repository in JSON.', | |
| 53 default='--json') | |
| 54 parser.add_option('--gae-sdk', | |
| 55 help='The path to the Google App Engine SDK. Defaults to finding the ' | |
| 56 'script in the PATH.', default='') | |
| 57 options, _ = parser.parse_args() | |
| 58 SetPackageRoot(options.pkg_root) | |
| 59 return options | |
| 60 | |
| 61 | |
| 62 def AddUserDocgenOptions(sdk_cmd, docgen_options, all_docs=False): | |
| 63 '''Expand the command with user specified docgen options.''' | |
| 64 specified_pkg = False | |
| 65 remove_append = False | |
| 66 append = '--append' | |
| 67 for option in docgen_options: | |
| 68 if '--package-root' in option: | |
| 69 specified_pkg = True | |
| 70 if option == append and all_docs: | |
| 71 remove_append = True | |
| 72 if remove_append: | |
| 73 docgen_options.remove(append) | |
| 74 if not specified_pkg: | |
| 75 sdk_cmd.extend(['--package-root=%s' % PACKAGE_ROOT]) | |
| 76 sdk_cmd.extend(docgen_options) | |
| 77 return sdk_cmd | |
| 78 | |
| 79 | |
| 80 def GenerateAllDocs(docgen_options): | |
| 81 '''Generate all documentation for the SDK and all packages in the repository. | |
| 82 We first attempt to run the quickest path to generate all docs, but if that | |
| 83 fails, we fall back on a slower option.''' | |
| 84 # TODO(alanknight): The --append option doesn't work properly. It overwrites | |
| 85 # existing files with new information. Known symptom is that it loses subclasses | |
| 86 # from the SDK and includes only the ones from pkg. So right now our only option | |
| 87 # is to do everything in one pass. | |
| 88 doc_dir = join(DART_DIR, 'pkg') | |
| 89 cmd_lst = [DART_EXECUTABLE, | |
| 90 '--package-root=%s' % PACKAGE_ROOT, 'docgen.dart', '--include-sdk' ] | |
| 91 cmd_str = ' '.join(AddUserDocgenOptions(cmd_lst, docgen_options, True)) | |
| 92 # Try to run all pkg docs together at once as it's fastest. | |
| 93 (return_code, _) = ExecuteCommandString('%s %s' % (cmd_str, doc_dir)) | |
| 94 if return_code != 0: | |
| 95 # We failed to run all the pkg docs, so try to generate docs for each pkg | |
| 96 # individually. | |
| 97 failed_pkgs = [] | |
| 98 for directory in os.listdir(join(DART_DIR, 'pkg')): | |
| 99 doc_dir = join(DART_DIR, 'pkg', directory) | |
| 100 if (directory not in EXCLUDED_PACKAGES and | |
| 101 os.path.isdir(doc_dir)): | |
| 102 (return_code, output) = ExecuteCommandString('%s %s' % (cmd_str, | |
| 103 doc_dir)) | |
| 104 if return_code != 0: | |
| 105 failed_pkgs += [directory] | |
| 106 print ('Generated documentation, but failed to generate documentation for ' | |
| 107 'the following packages, please investigate: %r' % failed_pkgs) | |
| 108 | |
| 109 | |
| 110 def ExecuteCommandString(cmd): | |
| 111 '''A variant of the ExecuteCommand function that specifically executes a | |
| 112 particular command string in the shell context. When you execute a string, you | |
| 113 must execute in the shell.''' | |
| 114 print 'Executing: %s ' % cmd | |
| 115 pipe = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, | |
| 116 shell=True) | |
| 117 output = pipe.communicate() | |
| 118 return (pipe.returncode, output) | |
| 119 | |
| 120 | |
| 121 def main(): | |
| 122 options = ParseArgs() | |
| 123 generate_all_docs = True | |
| 124 docgen_options = [] | |
| 125 if options.docgen_options: | |
| 126 # If the user specified particular files to generate docs for, then don't | |
| 127 # generate docs for everything. | |
| 128 docgen_options = options.docgen_options.split() | |
| 129 last_option = docgen_options[-1] | |
| 130 if '=' not in last_option and exists(last_option): | |
| 131 generate_all_docs = False | |
| 132 docgen = [DART_EXECUTABLE, '--checked', | |
| 133 '--package-root=' + PACKAGE_ROOT, join(DIRECTORY, 'docgen.dart')] | |
| 134 docgen.extend(options.options.split()) | |
| 135 utils.ExecuteCommand(docgen) | |
| 136 if generate_all_docs: | |
| 137 GenerateAllDocs(docgen_options) | |
| 138 if not options.just_docs: | |
| 139 cwd = os.getcwd() | |
| 140 try: | |
| 141 utils.ExecuteCommand(['git', 'clone', '-b', 'master', | |
| 142 'git://github.com/dart-lang/dartdoc-viewer.git']) | |
| 143 utils.ExecuteCommand(['mv', 'docs', 'dartdoc-viewer/client/local']) | |
| 144 os.chdir('dartdoc-viewer/client/') | |
| 145 subprocess.call([PUB, 'install']) | |
| 146 subprocess.call([DART_EXECUTABLE, 'deploy.dart']) | |
| 147 if options.gae_sdk == '': | |
| 148 server = subprocess.Popen(' '.join([APPSERVER_EXECUTABLE, '..']), | |
| 149 shell=True) | |
| 150 else: | |
| 151 path_to_gae = options.gae_sdk | |
| 152 if not path_to_gae.endswith(APPSERVER_EXECUTABLE): | |
| 153 path_to_gae = join(path_to_gae, APPSERVER_EXECUTABLE) | |
| 154 server = subprocess.Popen(join(['python', path_to_gae, '..'])) | |
| 155 print ( | |
| 156 "\nPoint your browser to the address of the 'default' server below.") | |
| 157 raw_input("Press <RETURN> to terminate the server.\n\n") | |
| 158 server.terminate() | |
| 159 finally: | |
| 160 os.chdir(cwd) | |
| 161 subprocess.call(['rm', '-rf', 'dartdoc-viewer']) | |
| 162 | |
| 163 if __name__ == '__main__': | |
| 164 main() | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 166093006:
pkg/docgen: removed py files, doc/README.txt, fixed analyzer warning (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart