createDartdocOptions function
- PackageMetaProvider packageMetaProvider
Instantiate dartdoc's configuration file and options parser with the given command line arguments.
Implementation
Future<List<DartdocOption<Object>>> createDartdocOptions(
PackageMetaProvider packageMetaProvider,
) async {
var resourceProvider = packageMetaProvider.resourceProvider;
return [
DartdocOptionArgOnly<bool>('allowTools', false, resourceProvider,
help: 'Execute user-defined tools to fill in @tool directives.',
negatable: true),
DartdocOptionArgFile<double>(
'ambiguousReexportScorerMinConfidence', 0.1, resourceProvider,
help: 'Minimum scorer confidence to suppress warning on ambiguous '
'reexport.'),
DartdocOptionArgOnly<bool>(
'autoIncludeDependencies', false, resourceProvider,
help: 'Include all the used libraries into the docs, even the ones not '
'in the current package or "include-external"',
negatable: true),
DartdocOptionArgFile<List<String>>('categoryOrder', [], resourceProvider,
help: 'A list of categories (not package names) to place first when '
"grouping symbols on dartdoc's sidebar. Unmentioned categories are "
'sorted after these.'),
DartdocOptionFileOnly<CategoryConfiguration>(
'categories', CategoryConfiguration.empty, resourceProvider,
convertYamlToType: CategoryConfiguration.fromYamlMap,
help: 'A list of all categories, their display names, and markdown '
'documentation in the order they are to be displayed.'),
DartdocOptionSyntheticOnly<List<String>>('dropTextFrom',
(DartdocSyntheticOption<List<String>> option, Folder dir) {
if (option.parent['hideSdkText'].valueAt(dir)) {
return [
'dart.async',
'dart.collection',
'dart.convert',
'dart.core',
'dart.developer',
'dart.html',
'dart.indexed_db',
'dart.io',
'dart.isolate',
'dart.js',
'dart.js_util',
'dart.math',
'dart.mirrors',
'dart.svg',
'dart.typed_data',
'dart.web_audio'
];
}
return [];
}, resourceProvider,
help: 'Remove text from libraries with the following names.'),
DartdocOptionArgFile<String>('examplePathPrefix', null, resourceProvider,
optionIs: OptionKind.dir,
help: 'Prefix for @example paths.\n(defaults to the project root)',
mustExist: true),
DartdocOptionArgFile<List<String>>('exclude', [], resourceProvider,
help: 'Library names to ignore.', splitCommas: true),
DartdocOptionArgOnly<List<String>>('excludePackages', [], resourceProvider,
help: 'Package names to ignore.', splitCommas: true),
DartdocOptionArgFile<bool>(
'experimentalReferenceLookup', false, resourceProvider,
hide: true,
help:
'Use an experimental code path to resolve comment reference lookups',
negatable: true),
// This could be a ArgOnly, but trying to not provide too many ways
// to set the flutter root.
DartdocOptionSyntheticOnly<String>(
'flutterRoot',
(DartdocSyntheticOption<String> option, Folder dir) => resourceProvider
.pathContext
.resolveTildePath(Platform.environment['FLUTTER_ROOT']),
resourceProvider,
optionIs: OptionKind.dir,
help: 'Root of the Flutter SDK, specified from environment.',
mustExist: true),
DartdocOptionArgOnly<bool>('hideSdkText', false, resourceProvider,
hide: true,
help: 'Drop all text for SDK components. Helpful for integration '
'tests for dartdoc, probably not useful for anything else.',
negatable: true),
DartdocOptionArgFile<List<String>>('include', [], resourceProvider,
help: 'Library names to generate docs for.', splitCommas: true),
DartdocOptionArgFile<List<String>>(
'includeExternal', null, resourceProvider,
optionIs: OptionKind.file,
help:
'Additional (external) dart files to include; use "dir/fileName", '
'as in lib/material.dart.',
mustExist: true,
splitCommas: true),
DartdocOptionArgOnly<bool>('includeSource', true, resourceProvider,
help: 'Show source code blocks.', negatable: true),
DartdocOptionArgOnly<bool>('injectHtml', false, resourceProvider,
help: 'Allow the use of the {@inject-html} directive to inject raw '
'HTML into dartdoc output.'),
DartdocOptionArgOnly<String>(
'input', resourceProvider.pathContext.current, resourceProvider,
optionIs: OptionKind.dir,
help: 'Path to source directory',
mustExist: true),
DartdocOptionSyntheticOnly<String>('inputDir',
(DartdocSyntheticOption<String> option, Folder dir) {
if (option.parent['sdkDocs'].valueAt(dir)) {
return option.parent['sdkDir'].valueAt(dir);
}
return option.parent['input'].valueAt(dir);
}, resourceProvider,
help: 'Path to source directory (with override if --sdk-docs)',
optionIs: OptionKind.dir,
mustExist: true),
DartdocOptionSet('linkTo', resourceProvider)
..addAll([
DartdocOptionArgOnly<Map<String, String>>(
'hosted',
{'pub.dartlang.org': 'https://pub.dev/documentation/%n%/%v%'},
resourceProvider,
help: 'Specify URLs for hosted pub packages'),
DartdocOptionArgOnly<Map<String, String>>(
'sdks',
{
'Dart': 'https://api.dart.dev/%b%/%v%',
'Flutter': 'https://api.flutter.dev/flutter',
},
resourceProvider,
help: 'Specify URLs for SDKs.',
),
DartdocOptionFileSynth<String>('url',
(DartdocSyntheticOption<String> option, Folder dir) {
PackageMeta packageMeta =
option.parent.parent['packageMeta'].valueAt(dir);
// Prefer SDK check first, then pub cache check.
var inSdk = packageMeta
.sdkType(option.parent.parent['flutterRoot'].valueAt(dir));
if (inSdk != null) {
Map<String, String> sdks = option.parent['sdks'].valueAt(dir);
if (sdks.containsKey(inSdk)) return sdks[inSdk];
}
var hostedAt = packageMeta.hostedAt;
if (hostedAt != null) {
Map<String, String> hostMap = option.parent['hosted'].valueAt(dir);
if (hostMap.containsKey(hostedAt)) return hostMap[hostedAt];
}
return '';
}, resourceProvider, help: 'Url to use for this particular package.'),
DartdocOptionArgOnly<bool>('remote', true, resourceProvider,
help: 'Allow links to be generated for packages outside this one.',
negatable: true),
]),
DartdocOptionFileOnly<List<String>>('nodoc', [], resourceProvider,
optionIs: OptionKind.glob,
help: 'Dart symbols declared in these '
'files will be treated as though they have the @nodoc flag added to '
'their documentation comment.'),
DartdocOptionArgOnly<String>('output',
resourceProvider.pathContext.join('doc', 'api'), resourceProvider,
optionIs: OptionKind.dir, help: 'Path to output directory.'),
DartdocOptionSyntheticOnly<PackageMeta>(
'packageMeta',
(DartdocSyntheticOption<PackageMeta> option, Folder dir) {
var packageMeta = packageMetaProvider.fromDir(dir);
if (packageMeta == null) {
throw DartdocOptionError(
'Unable to determine package for directory: ${dir.path}');
}
return packageMeta;
},
resourceProvider,
),
DartdocOptionArgOnly<List<String>>('packageOrder', [], resourceProvider,
help:
'A list of package names to place first when grouping libraries in '
'packages. Unmentioned packages are sorted after these.'),
DartdocOptionArgOnly<bool>('sdkDocs', false, resourceProvider,
help: 'Generate ONLY the docs for the Dart SDK.'),
DartdocOptionArgSynth<String>('sdkDir',
(DartdocSyntheticOption<String> option, Folder dir) {
if (!(option.parent['sdkDocs'].valueAt(dir) as bool) &&
(option.root['topLevelPackageMeta'].valueAt(dir) as PackageMeta)
.requiresFlutter) {
String flutterRoot = option.root['flutterRoot'].valueAt(dir);
if (flutterRoot == null) {
// For now, return null. An error is reported in
// [PackageBuilder.buildPackageGraph].
return null;
}
return resourceProvider.pathContext
.join(flutterRoot, 'bin', 'cache', 'dart-sdk');
}
return packageMetaProvider.defaultSdkDir.path;
}, packageMetaProvider.resourceProvider,
help: 'Path to the SDK directory.',
optionIs: OptionKind.dir,
mustExist: true),
DartdocOptionArgFile<bool>(
'showUndocumentedCategories', false, resourceProvider,
help: "Label categories that aren't documented", negatable: true),
DartdocOptionSyntheticOnly<PackageMeta>('topLevelPackageMeta',
(DartdocSyntheticOption<PackageMeta> option, Folder dir) {
var packageMeta = packageMetaProvider.fromDir(
resourceProvider.getFolder(option.parent['inputDir'].valueAt(dir)));
if (packageMeta == null) {
throw DartdocOptionError(
'Unable to generate documentation: no package found');
}
if (!packageMeta.isValid) {
final firstError = packageMeta.getInvalidReasons().first;
throw DartdocOptionError('Package is invalid: $firstError');
}
return packageMeta;
}, resourceProvider, help: 'PackageMeta object for the default package.'),
DartdocOptionArgOnly<bool>('useCategories', true, resourceProvider,
help: 'Display categories in the sidebar of packages'),
DartdocOptionArgOnly<bool>('validateLinks', true, resourceProvider,
help: 'Runs the built-in link checker to display Dart context aware '
'warnings for broken links (slow)',
negatable: true),
DartdocOptionArgOnly<bool>('verboseWarnings', true, resourceProvider,
help: 'Display extra debugging information and help with warnings.',
negatable: true),
DartdocOptionFileOnly<bool>('excludeFooterVersion', false, resourceProvider,
help: 'Excludes the package version number in the footer text'),
DartdocOptionFileOnly<ToolConfiguration>(
'tools', ToolConfiguration.empty(resourceProvider), resourceProvider,
convertYamlToType: ToolConfiguration.fromYamlMap,
help: 'A map of tool names to executable paths. Each executable must '
'exist. Executables for different platforms are specified by '
'giving the platform name as a key, and a list of strings as the '
'command.'),
DartdocOptionArgOnly<bool>('useBaseHref', false, resourceProvider,
help:
'Use <base href> in generated files (legacy behavior). This option '
'is temporary and support will be removed in the future. Use only '
'if the default behavior breaks links between your documentation '
'pages, and please file an issue on GitHub.',
negatable: false,
hide: true),
DartdocOptionArgOnly<bool>('showStats', false, resourceProvider,
help: 'Show statistics useful for debugging.', hide: true),
// TODO(jdkoren): Unhide when we have good support for another format.
DartdocOptionArgOnly<String>('format', 'html', resourceProvider,
hide: true),
// TODO(jcollins-g): refactor so there is a single static "create" for
// each DartdocOptionContext that traverses the inheritance tree itself.
...await createExperimentOptions(resourceProvider),
...await createPackageWarningOptions(packageMetaProvider),
...await createSourceLinkerOptions(resourceProvider),
];
}