diff --git a/bin/dartdoc.dart b/bin/dartdoc.dart index 1e78f1b6ed..5c4b11882b 100644 --- a/bin/dartdoc.dart +++ b/bin/dartdoc.dart @@ -6,8 +6,8 @@ library dartdoc.bin; import 'dart:async'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:dartdoc/src/package_config_provider.dart'; import 'package:dartdoc/src/package_meta.dart'; diff --git a/lib/options.dart b/lib/options.dart index 6610d83909..b75f21541e 100644 --- a/lib/options.dart +++ b/lib/options.dart @@ -1,153 +1,7 @@ -import 'dart:io' show stderr, exitCode; +// Copyright (c) 2023, 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. -import 'package:args/args.dart'; -import 'package:dartdoc/src/dartdoc.dart' show dartdocVersion, programName; -import 'package:dartdoc/src/dartdoc_options.dart'; -import 'package:dartdoc/src/generator/generator.dart'; -import 'package:dartdoc/src/logging.dart'; -import 'package:dartdoc/src/package_meta.dart'; - -/// Helper class that consolidates option contexts for instantiating generators. -class DartdocGeneratorOptionContext extends DartdocOptionContext { - DartdocGeneratorOptionContext( - super.optionSet, super.dir, super.resourceProvider); - DartdocGeneratorOptionContext.fromDefaultContextLocation( - super.optionSet, super.resourceProvider) - : super.fromDefaultContextLocation(); - - /// The joined contents of any 'header' files specified in options. - String get header => - _joinCustomTextFiles(optionSet['header'].valueAt(context)); - - /// The joined contents of any 'footer' files specified in options. - String get footer => - _joinCustomTextFiles(optionSet['footer'].valueAt(context)); - - /// The joined contents of any 'footer-text' files specified in options. - String get footerText => - _joinCustomTextFiles(optionSet['footerText'].valueAt(context)); - - String _joinCustomTextFiles(Iterable paths) => paths - .map((p) => resourceProvider.getFile(p).readAsStringSync()) - .join('\n'); - - bool get prettyIndexJson => optionSet['prettyIndexJson'].valueAt(context); - - String? get favicon => optionSet['favicon'].valueAt(context); - - String? get relCanonicalPrefix => - optionSet['relCanonicalPrefix'].valueAt(context); - - String? get templatesDir => optionSet['templatesDir'].valueAt(context); - - // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration. - @override - bool get useBaseHref => optionSet['useBaseHref'].valueAt(context); - - String? get resourcesDir => optionSet['resourcesDir'].valueAt(context); -} - -class DartdocProgramOptionContext extends DartdocGeneratorOptionContext - with LoggingContext { - DartdocProgramOptionContext( - super.optionSet, super.dir, super.resourceProvider); - - DartdocProgramOptionContext.fromDefaultContextLocation( - super.optionSet, super.resourceProvider) - : super.fromDefaultContextLocation(); - - /// Whether to generate docs or perform a dry run. - bool get generateDocs => optionSet['generateDocs'].valueAt(context); - bool get help => optionSet['help'].valueAt(context); - bool get version => optionSet['version'].valueAt(context); -} - -List> createDartdocProgramOptions( - PackageMetaProvider packageMetaProvider) { - var resourceProvider = packageMetaProvider.resourceProvider; - return [ - DartdocOptionArgOnly('generateDocs', true, resourceProvider, - help: - 'Generate docs into the output directory (or only display warnings ' - 'if false).', - negatable: true), - DartdocOptionArgOnly('help', false, resourceProvider, - abbr: 'h', help: 'Show command help.', negatable: false), - DartdocOptionArgOnly('version', false, resourceProvider, - help: 'Display the version for $programName.', negatable: false), - ]; -} - -DartdocProgramOptionContext? parseOptions( - PackageMetaProvider packageMetaProvider, - List arguments, { - // Additional options are given in google3. - OptionGenerator? additionalOptions, -}) { - var optionRoot = DartdocOptionRoot.fromOptionGenerators( - 'dartdoc', - [ - createDartdocOptions, - createDartdocProgramOptions, - createLoggingOptions, - createGeneratorOptions, - if (additionalOptions != null) additionalOptions, - ], - packageMetaProvider); - - try { - optionRoot.parseArguments(arguments); - } on FormatException catch (e) { - stderr.writeln(' fatal error: ${e.message}'); - stderr.writeln(''); - _printUsage(optionRoot.argParser); - // Do not use `exit()` as this bypasses `--pause-isolates-on-exit`. - exitCode = 64; - return null; - } - if (optionRoot['help'].valueAtCurrent() as bool) { - _printHelp(optionRoot.argParser); - exitCode = 0; - return null; - } - if (optionRoot['version'].valueAtCurrent() as bool) { - _printVersion(optionRoot.argParser); - exitCode = 0; - return null; - } - - DartdocProgramOptionContext config; - try { - config = DartdocProgramOptionContext.fromDefaultContextLocation( - optionRoot, packageMetaProvider.resourceProvider); - } on DartdocOptionError catch (e) { - stderr.writeln(' fatal error: ${e.message}'); - stderr.writeln(''); - _printUsage(optionRoot.argParser); - exitCode = 64; - return null; - } - startLogging( - isJson: config.json, - isQuiet: config.quiet, - showProgress: config.showProgress, - ); - return config; -} - -/// Print help if we are passed the help option. -void _printHelp(ArgParser parser) { - print('Generate HTML documentation for Dart libraries.\n'); - print(parser.usage); -} - -/// Print usage information on invalid command lines. -void _printUsage(ArgParser parser) { - print('Usage: dartdoc [OPTIONS]\n'); - print(parser.usage); -} - -/// Print version information. -void _printVersion(ArgParser parser) { - print('dartdoc version: $dartdocVersion'); -} +@Deprecated( + 'Will be removed in a later version of DartDoc. Use /src/dartdoc_options.dart.') +export 'package:dartdoc/src/dartdoc_options.dart'; diff --git a/lib/src/dartdoc.dart b/lib/src/dartdoc.dart index c9a98e9eae..9bce7e1208 100644 --- a/lib/src/dartdoc.dart +++ b/lib/src/dartdoc.dart @@ -7,7 +7,6 @@ import 'dart:convert'; import 'dart:io' show Platform, exitCode, stderr; import 'package:analyzer/file_system/file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/failure.dart'; import 'package:dartdoc/src/generator/empty_generator.dart'; diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index f34e603a99..c4b11a8750 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -14,14 +14,17 @@ /// library dartdoc.dartdoc_options; -import 'dart:io' show Platform, stdout; +import 'dart:io' show Platform, exitCode, stderr, stdout; import 'package:analyzer/dart/element/element.dart'; import 'package:analyzer/file_system/file_system.dart'; import 'package:args/args.dart'; +import 'package:dartdoc/src/dartdoc.dart' show dartdocVersion, programName; import 'package:dartdoc/src/experiment_options.dart'; import 'package:dartdoc/src/failure.dart'; +import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/io_utils.dart'; +import 'package:dartdoc/src/logging.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:dartdoc/src/package_meta.dart'; import 'package:dartdoc/src/source_linker.dart'; @@ -1340,6 +1343,151 @@ class DartdocOptionContext extends DartdocOptionContextBase int.parse(optionSet['maxTotalSize'].valueAt(context) ?? '0'); } +/// Helper class that consolidates option contexts for instantiating generators. +class DartdocGeneratorOptionContext extends DartdocOptionContext { + DartdocGeneratorOptionContext( + super.optionSet, super.dir, super.resourceProvider); + DartdocGeneratorOptionContext.fromDefaultContextLocation( + super.optionSet, super.resourceProvider) + : super.fromDefaultContextLocation(); + + /// The joined contents of any 'header' files specified in options. + String get header => + _joinCustomTextFiles(optionSet['header'].valueAt(context)); + + /// The joined contents of any 'footer' files specified in options. + String get footer => + _joinCustomTextFiles(optionSet['footer'].valueAt(context)); + + /// The joined contents of any 'footer-text' files specified in options. + String get footerText => + _joinCustomTextFiles(optionSet['footerText'].valueAt(context)); + + String _joinCustomTextFiles(Iterable paths) => paths + .map((p) => resourceProvider.getFile(p).readAsStringSync()) + .join('\n'); + + bool get prettyIndexJson => optionSet['prettyIndexJson'].valueAt(context); + + String? get favicon => optionSet['favicon'].valueAt(context); + + String? get relCanonicalPrefix => + optionSet['relCanonicalPrefix'].valueAt(context); + + String? get templatesDir => optionSet['templatesDir'].valueAt(context); + + // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration. + @override + bool get useBaseHref => optionSet['useBaseHref'].valueAt(context); + + String? get resourcesDir => optionSet['resourcesDir'].valueAt(context); +} + +class DartdocProgramOptionContext extends DartdocGeneratorOptionContext + with LoggingContext { + DartdocProgramOptionContext( + super.optionSet, super.dir, super.resourceProvider); + + DartdocProgramOptionContext.fromDefaultContextLocation( + super.optionSet, super.resourceProvider) + : super.fromDefaultContextLocation(); + + /// Whether to generate docs or perform a dry run. + bool get generateDocs => optionSet['generateDocs'].valueAt(context); + bool get help => optionSet['help'].valueAt(context); + bool get version => optionSet['version'].valueAt(context); +} + +List> createDartdocProgramOptions( + PackageMetaProvider packageMetaProvider) { + var resourceProvider = packageMetaProvider.resourceProvider; + return [ + DartdocOptionArgOnly('generateDocs', true, resourceProvider, + help: + 'Generate docs into the output directory (or only display warnings ' + 'if false).', + negatable: true), + DartdocOptionArgOnly('help', false, resourceProvider, + abbr: 'h', help: 'Show command help.', negatable: false), + DartdocOptionArgOnly('version', false, resourceProvider, + help: 'Display the version for $programName.', negatable: false), + ]; +} + +DartdocProgramOptionContext? parseOptions( + PackageMetaProvider packageMetaProvider, + List arguments, { + // Additional options are given in google3. + OptionGenerator? additionalOptions, +}) { + var optionRoot = DartdocOptionRoot.fromOptionGenerators( + 'dartdoc', + [ + createDartdocOptions, + createDartdocProgramOptions, + createLoggingOptions, + createGeneratorOptions, + if (additionalOptions != null) additionalOptions, + ], + packageMetaProvider); + + try { + optionRoot.parseArguments(arguments); + } on FormatException catch (e) { + stderr.writeln(' fatal error: ${e.message}'); + stderr.writeln(''); + _printUsage(optionRoot.argParser); + // Do not use `exit()` as this bypasses `--pause-isolates-on-exit`. + exitCode = 64; + return null; + } + if (optionRoot['help'].valueAtCurrent() as bool) { + _printHelp(optionRoot.argParser); + exitCode = 0; + return null; + } + if (optionRoot['version'].valueAtCurrent() as bool) { + _printVersion(optionRoot.argParser); + exitCode = 0; + return null; + } + + DartdocProgramOptionContext config; + try { + config = DartdocProgramOptionContext.fromDefaultContextLocation( + optionRoot, packageMetaProvider.resourceProvider); + } on DartdocOptionError catch (e) { + stderr.writeln(' fatal error: ${e.message}'); + stderr.writeln(''); + _printUsage(optionRoot.argParser); + exitCode = 64; + return null; + } + startLogging( + isJson: config.json, + isQuiet: config.quiet, + showProgress: config.showProgress, + ); + return config; +} + +/// Print help if we are passed the help option. +void _printHelp(ArgParser parser) { + print('Generate HTML documentation for Dart libraries.\n'); + print(parser.usage); +} + +/// Print usage information on invalid command lines. +void _printUsage(ArgParser parser) { + print('Usage: dartdoc [OPTIONS]\n'); + print(parser.usage); +} + +/// Print version information. +void _printVersion(ArgParser parser) { + print('dartdoc version: $dartdocVersion'); +} + /// Instantiate dartdoc's configuration file and options parser with the /// given command line arguments. List createDartdocOptions( diff --git a/lib/src/generator/generator_backend.dart b/lib/src/generator/generator_backend.dart index e6a29c1718..522fb399d1 100644 --- a/lib/src/generator/generator_backend.dart +++ b/lib/src/generator/generator_backend.dart @@ -3,7 +3,7 @@ // BSD-style license that can be found in the LICENSE file. import 'package:analyzer/file_system/file_system.dart'; -import 'package:dartdoc/options.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/generator/generator_utils.dart' as generator_util; import 'package:dartdoc/src/generator/template_data.dart'; diff --git a/lib/src/generator/html_generator.dart b/lib/src/generator/html_generator.dart index 24de548072..feb8b729a0 100644 --- a/lib/src/generator/html_generator.dart +++ b/lib/src/generator/html_generator.dart @@ -4,7 +4,7 @@ library dartdoc.html_generator; -import 'package:dartdoc/options.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/generator/generator_backend.dart'; import 'package:dartdoc/src/generator/generator_frontend.dart'; diff --git a/lib/src/generator/markdown_generator.dart b/lib/src/generator/markdown_generator.dart index 21d7caf14f..6c4d201683 100644 --- a/lib/src/generator/markdown_generator.dart +++ b/lib/src/generator/markdown_generator.dart @@ -2,7 +2,7 @@ // 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. -import 'package:dartdoc/options.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/generator/generator_backend.dart'; import 'package:dartdoc/src/generator/generator_frontend.dart'; diff --git a/lib/src/generator/templates.dart b/lib/src/generator/templates.dart index b5500904a7..1445e258c6 100644 --- a/lib/src/generator/templates.dart +++ b/lib/src/generator/templates.dart @@ -39,7 +39,7 @@ library dartdoc.templates; import 'package:analyzer/file_system/file_system.dart'; -import 'package:dartdoc/options.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/element_type.dart'; import 'package:dartdoc/src/failure.dart'; import 'package:dartdoc/src/generator/resource_loader.dart'; diff --git a/test/end2end/dartdoc_test.dart b/test/end2end/dartdoc_test.dart index 7680327003..438a27e319 100644 --- a/test/end2end/dartdoc_test.dart +++ b/test/end2end/dartdoc_test.dart @@ -7,7 +7,6 @@ library dartdoc.dartdoc_test; import 'dart:async'; import 'package:analyzer/file_system/file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart' show Dartdoc, DartdocResults; import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/failure.dart'; diff --git a/test/html_generator_test.dart b/test/html_generator_test.dart index 93451d8008..202cf2f121 100644 --- a/test/html_generator_test.dart +++ b/test/html_generator_test.dart @@ -4,7 +4,6 @@ import 'package:analyzer/file_system/file_system.dart'; import 'package:analyzer/file_system/memory_file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart' show DartdocFileWriter; import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/generator/generator.dart'; diff --git a/test/mustachio/renderers_output_test.dart b/test/mustachio/renderers_output_test.dart index 227dea28f8..9ab8285328 100644 --- a/test/mustachio/renderers_output_test.dart +++ b/test/mustachio/renderers_output_test.dart @@ -9,7 +9,6 @@ import 'dart:io'; import 'package:analyzer/file_system/file_system.dart'; import 'package:analyzer/file_system/memory_file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart' show Dartdoc, DartdocFileWriter; import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/generator/generator.dart'; diff --git a/test/src/utils.dart b/test/src/utils.dart index 9604b90c86..f95ad09547 100644 --- a/test/src/utils.dart +++ b/test/src/utils.dart @@ -9,7 +9,6 @@ import 'package:analyzer/file_system/memory_file_system.dart'; import 'package:analyzer/file_system/physical_file_system.dart'; import 'package:analyzer/src/dart/sdk/sdk.dart'; import 'package:analyzer/src/test_utilities/mock_sdk.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/failure.dart'; import 'package:dartdoc/src/generator/generator.dart'; diff --git a/test/templates/category_test.dart b/test/templates/category_test.dart index af65866b51..4e1fd0ee2a 100644 --- a/test/templates/category_test.dart +++ b/test/templates/category_test.dart @@ -3,8 +3,8 @@ // BSD-style license that can be found in the LICENSE file. import 'package:analyzer/file_system/memory_file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:dartdoc/src/package_meta.dart'; import 'package:path/path.dart' as path; diff --git a/test/templates/extension_test.dart b/test/templates/extension_test.dart index bc28c56a55..36fe9a5d2c 100644 --- a/test/templates/extension_test.dart +++ b/test/templates/extension_test.dart @@ -3,8 +3,8 @@ // BSD-style license that can be found in the LICENSE file. import 'package:analyzer/file_system/memory_file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:dartdoc/src/package_meta.dart'; import 'package:path/path.dart' as path; diff --git a/test/templates/extension_type_test.dart b/test/templates/extension_type_test.dart index ecd52eba7f..e0a559a4ed 100644 --- a/test/templates/extension_type_test.dart +++ b/test/templates/extension_type_test.dart @@ -3,8 +3,8 @@ // BSD-style license that can be found in the LICENSE file. import 'package:analyzer/file_system/memory_file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc.dart'; +import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:dartdoc/src/package_meta.dart'; import 'package:path/path.dart' as path; diff --git a/test/warnings_test.dart b/test/warnings_test.dart index 9ba62ef11b..33ed00b9d9 100644 --- a/test/warnings_test.dart +++ b/test/warnings_test.dart @@ -6,7 +6,6 @@ library dartdoc.warnings_test; import 'package:analyzer/file_system/physical_file_system.dart'; -import 'package:dartdoc/options.dart'; import 'package:dartdoc/src/dartdoc_options.dart'; import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/io_utils.dart';