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 [
DartdocOptionArgFile<String>(
'format',
'jaspr',
resourceProvider,
help: 'Output format: jaspr, vitepress, or html.',
),
DartdocOptionArgFile<String?>(
'recipe',
null,
resourceProvider,
help: 'Documentation recipe. Supported: self-docs.',
),
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',
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,
),
DartdocOptionArgOnly<bool>(
'workspaceDocs',
false,
resourceProvider,
help:
'Auto-detect workspace packages from the root pubspec.yaml '
"'workspace:' key and document them as local packages.",
negatable: true,
),
DartdocOptionArgOnly<List<String>>(
'includePackages',
[],
resourceProvider,
help:
'Names of packages to force-include as local (manual override '
'for multi-package documentation).',
splitCommas: true,
),
DartdocOptionSet('guide', resourceProvider)..addAll([
DartdocOptionArgFile<List<String>>(
'dirs',
['doc', 'docs'],
resourceProvider,
help: 'Directory names to scan for guide markdown files.',
splitCommas: true,
),
DartdocOptionArgFile<List<String>>(
'include',
[],
resourceProvider,
help: 'Regexp patterns for guide file paths to include.',
splitCommas: true,
),
DartdocOptionArgFile<List<String>>(
'exclude',
[],
resourceProvider,
help: 'Regexp patterns for guide file paths to exclude.',
splitCommas: true,
),
]),
DartdocOptionSyntheticOnly<String?>(
'flutterRoot',
(DartdocSyntheticOption<String?> option, Folder dir) {
var flutterRootEnv =
packageMetaProvider.environmentProvider['FLUTTER_ROOT'];
if (flutterRootEnv != null) {
return resourceProvider.pathContext.resolveTildePath(flutterRootEnv);
}
return _inferFlutterRoot(packageMetaProvider);
},
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,
),
DartdocOptionArgOnly<bool>(
'includeSource',
true,
resourceProvider,
help: 'Show source code blocks.',
negatable: true,
),
DartdocOptionArgFile<List<String>>(
'allowedIframeHosts',
[],
resourceProvider,
help:
'Additional hostnames whose <iframe> elements are preserved '
'during HTML sanitization. YouTube and DartPad hosts are always '
'allowed. Example: codepen.io,stackblitz.com',
splitCommas: 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,
),
]),
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.',
),
DartdocOptionArgOnly<String?>(
'resourcesDir',
null,
resourceProvider,
help: "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);
if (flutterRoot == null) {
throw DartdocOptionError(
'Flutter package detected, but no Flutter SDK root could be '
'resolved. Set FLUTTER_ROOT or pass --sdk-dir explicitly.',
);
}
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: 'Deprecated, has no effect.',
hide: true,
),
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),
];
}