runDartDoc method

Progress runDartDoc({
  1. String? pathToProject,
  2. String? pathToDoc,
  3. List<String> args = const [],
  4. Progress? progress,
  5. bool nothrow = false,
})

Runs the 'dart doc' command with the given arguments.

pathToProject is the location of the dart project. If pathToProject is not supplied the current working directory is used.

pathToDoc is the path where the generated docs are to be saved. If not supplied then it is placed under a 'doc/api' directory in pathToProject. pathToDoc may be an absolute or relative path. A relative path is assumed to be relative to pathToProject

By default stdout and stderr are sent to the console.

Pass in progress to control the output. If nothrow == true (defaults to false) then if the call to pub get fails an exit code will be returned in the Progress rather than throwing an exception.

Implementation

Progress runDartDoc({
  String? pathToProject,
  String? pathToDoc,
  List<String> args = const [],
  Progress? progress,
  bool nothrow = false,
}) {
  pathToProject ??= pwd;
  pathToDoc ??= join(pathToProject, 'doc/api');

  progress ??= Progress.print();

  // if [pathToDoc] is absolute then it will be used
  // other wise it is treated as relative to pathToProject
  final docPath = join(pathToProject, pathToDoc);

  // ignore: parameter_assignments
  args = ['--output-dir', docPath, ...args];

  if (useDartDocCommand) {
    final w = which('dartdoc');
    if (w.notfound) {
      throw DCliException(
          "Unable to run 'dartdoc' as the exe is not on your path");
    }
    startFromArgs(
      w.path!,
      args,
      nothrow: nothrow,
      progress: progress,
      workingDirectory: pathToProject,
      extensionSearch: false,
    );
  } else {
    if (pathToDartExe == null) {
      throw DCliException(
        "Unable to run 'dart doc' as the dart exe is not on your path",
      );
    }
    startFromArgs(
      pathToDartExe!,
      ['doc', ...args, '.'],
      nothrow: nothrow,
      progress: progress,
      workingDirectory: pathToProject,
      extensionSearch: false,
    );
  }
  verbose(() => 'dart doc ${args.toList().join(' ')} finished.');

  return progress;
}