Deprecate options.dart. (#3591)
diff --git a/bin/dartdoc.dart b/bin/dartdoc.dart
index 1e78f1b..5c4b118 100644
--- a/bin/dartdoc.dart
+++ b/bin/dartdoc.dart
@@ -6,8 +6,8 @@
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 6610d83..b75f215 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<String> 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<DartdocOption<bool>> createDartdocProgramOptions(
- PackageMetaProvider packageMetaProvider) {
- var resourceProvider = packageMetaProvider.resourceProvider;
- return [
- DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
- help:
- 'Generate docs into the output directory (or only display warnings '
- 'if false).',
- negatable: true),
- DartdocOptionArgOnly<bool>('help', false, resourceProvider,
- abbr: 'h', help: 'Show command help.', negatable: false),
- DartdocOptionArgOnly<bool>('version', false, resourceProvider,
- help: 'Display the version for $programName.', negatable: false),
- ];
-}
-
-DartdocProgramOptionContext? parseOptions(
- PackageMetaProvider packageMetaProvider,
- List<String> 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 c9a98e9..9bce7e1 100644
--- a/lib/src/dartdoc.dart
+++ b/lib/src/dartdoc.dart
@@ -7,7 +7,6 @@
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 f34e603..c4b11a8 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 @@
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<String> 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<DartdocOption<bool>> createDartdocProgramOptions(
+ PackageMetaProvider packageMetaProvider) {
+ var resourceProvider = packageMetaProvider.resourceProvider;
+ return [
+ DartdocOptionArgOnly<bool>('generateDocs', true, resourceProvider,
+ help:
+ 'Generate docs into the output directory (or only display warnings '
+ 'if false).',
+ negatable: true),
+ DartdocOptionArgOnly<bool>('help', false, resourceProvider,
+ abbr: 'h', help: 'Show command help.', negatable: false),
+ DartdocOptionArgOnly<bool>('version', false, resourceProvider,
+ help: 'Display the version for $programName.', negatable: false),
+ ];
+}
+
+DartdocProgramOptionContext? parseOptions(
+ PackageMetaProvider packageMetaProvider,
+ List<String> 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<DartdocOption> createDartdocOptions(
diff --git a/lib/src/generator/generator_backend.dart b/lib/src/generator/generator_backend.dart
index e6a29c1..522fb39 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 24de548..feb8b72 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 21d7caf..6c4d201 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 b550090..1445e25 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 7680327..438a27e 100644
--- a/test/end2end/dartdoc_test.dart
+++ b/test/end2end/dartdoc_test.dart
@@ -7,7 +7,6 @@
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 93451d8..202cf2f 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 227dea2..9ab8285 100644
--- a/test/mustachio/renderers_output_test.dart
+++ b/test/mustachio/renderers_output_test.dart
@@ -9,7 +9,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 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 9604b90..f95ad09 100644
--- a/test/src/utils.dart
+++ b/test/src/utils.dart
@@ -9,7 +9,6 @@
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 af65866..4e1fd0e 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 bc28c56..36fe9a5 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 ecd52eb..e0a559a 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 9ba62ef..33ed00b 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';
