createDartdocOptions function
Instantiate dartdoc's configuration file and options parser with the given command line arguments.
Implementation
List<DartdocOption> createDartdocOptions(
PackageMetaProvider packageMetaProvider,
) {
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', const [], resourceProvider,
splitCommas: true,
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.'),
DartdocOptionArgFile<List<String>>('exclude', [], resourceProvider,
help: 'Names of libraries to exclude from documentation.',
splitCommas: true),
DartdocOptionArgOnly<List<String>>('excludePackages', [], resourceProvider,
help: 'Names of packages to exclude from documentation.',
splitCommas: true),
DartdocOptionSyntheticOnly<String?>('flutterRoot',
(DartdocSyntheticOption<String?> option, Folder dir) {
var flutterRootEnv =
packageMetaProvider.environmentProvider['FLUTTER_ROOT'];
return flutterRootEnv == null
? null
: resourceProvider.pathContext.resolveTildePath(flutterRootEnv);
}, resourceProvider,
optionIs: OptionKind.dir,
help: 'Root of the Flutter SDK, specified from the environment.',
mustExist: true),
DartdocOptionArgFile<List<String>>('include', [], resourceProvider,
help: 'Names of libraries to document.', splitCommas: true),
DartdocOptionArgFile<List<String>>('includeExternal', [], resourceProvider,
optionIs: OptionKind.file,
help: 'Additional (external) dart files to include; use '
'"<directory name>/<file name>", 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<bool>('sanitizeHtml', false, resourceProvider,
hide: true,
help: 'Sanitize HTML generated from markdown text, `{@tool}` and '
'`{@inject-html}` directives.'),
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) =>
option.parent['sdkDocs'].valueAt(dir) == true
? option.parent['sdkDir'].valueAt(dir)
: 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%',
'pub.dev': '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);
var inSdkVal = sdks[inSdk];
if (inSdkVal != null) return inSdkVal;
}
var hostedAt = packageMeta.hostedAt;
if (hostedAt != null) {
Map<String, String> hostMap = option.parent['hosted'].valueAt(dir);
var hostedAtVal = hostMap[hostedAt];
if (hostedAtVal != null) return hostedAtVal;
}
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),
]),
// Deprecated. Use of this option is reported.
// TODO(srawlins): Remove.
DartdocOptionFileOnly<List<String>>('nodoc', [], resourceProvider,
optionIs: OptionKind.glob,
help: '(deprecated) Dart symbols declared in these files will be '
'treated as though they have the @nodoc directive added to their '
'documentation comment.'),
DartdocOptionArgOnly<String>('output',
resourceProvider.pathContext.join('doc', 'api'), resourceProvider,
optionIs: OptionKind.dir, help: 'Path to the 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,
splitCommas: true,
help:
'A list of package names to place first when grouping libraries in '
'packages. Unmentioned packages are placed after these.'),
// Deprecated. Use of this option is reported.
// TODO(kallentu): Remove this option.
DartdocOptionArgOnly<String?>('resourcesDir', null, resourceProvider,
help: "(deprecated) An absolute path to dartdoc's resources directory.",
hide: true),
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);
return flutterRoot == null
? null
: 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),
DartdocOptionArgOnly<String>('maxFileCount', '0', resourceProvider,
help:
'The maximum number of files dartdoc is allowed to create (0 for no limit).',
hide: true),
DartdocOptionArgOnly<String>('maxTotalSize', '0', resourceProvider,
help:
'The maximum total size (in bytes) dartdoc is allowed to write (0 for no limit).',
hide: true),
// TODO(jcollins-g): refactor so there is a single static "create" for
// each DartdocOptionContext that traverses the inheritance tree itself.
...createExperimentOptions(resourceProvider),
...createPackageWarningOptions(packageMetaProvider),
...createSourceLinkerOptions(resourceProvider),
];
}