From 2de17d6de8f7f070d7ca4c8614bff84c6030278d Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:36:05 -0700 Subject: [PATCH 1/5] Remove the deprecated templates-dir option --- lib/src/dartdoc_options.dart | 3 -- lib/src/generator/generator.dart | 17 ------- lib/src/generator/templates.dart | 12 ++--- test/options_test.dart | 82 -------------------------------- 4 files changed, 4 insertions(+), 110 deletions(-) diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index 79c1a2a59c..e0eef7fa4c 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -1278,9 +1278,6 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext { String? get relCanonicalPrefix => optionSet['relCanonicalPrefix'].valueAt(context); - // TODO(kallentu): Remove --templates-dir completely. - 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); diff --git a/lib/src/generator/generator.dart b/lib/src/generator/generator.dart index a97d81c353..13511dc134 100644 --- a/lib/src/generator/generator.dart +++ b/lib/src/generator/generator.dart @@ -82,22 +82,5 @@ List createGeneratorOptions( 'If provided, add a rel="canonical" prefixed with provided value. ' 'Consider using if building many versions of the docs for public ' 'SEO; learn more at https://goo.gl/gktN6F.'), - // TODO(kallentu): Remove --templates-dir completely. - DartdocOptionArgOnly( - 'templatesDir', - null, - resourceProvider, - optionIs: OptionKind.dir, - mustExist: true, - hide: true, - help: '(deprecated) Path to a directory with templates to use instead of ' - 'the default ones. Directory must contain a file for each of the ' - 'following: 404error, category, class, constant, constructor, ' - 'enum, function, index, library, method, mixin, property, ' - 'top_level_constant, top_level_property, typedef. Partial ' - 'templates are supported; they must begin with an underscore, and ' - 'references to them must omit the leading underscore ' - '(e.g. use {{>foo}} to reference the partial template named _foo).', - ), ]; } diff --git a/lib/src/generator/templates.dart b/lib/src/generator/templates.dart index 4fcd71becb..e66654d234 100644 --- a/lib/src/generator/templates.dart +++ b/lib/src/generator/templates.dart @@ -112,18 +112,14 @@ abstract class Templates { String renderTopLevelProperty(TopLevelPropertyTemplateData context); String renderTypedef(TypedefTemplateData context); - /// Creates a [Templates] instance either from the default set of templates, - /// or a custom set if the 'templatesDir' Dartdoc option is used. + /// Creates a [Templates] instance from the default set of templates. /// /// [forceRuntimeTemplates] should only be given `true` during tests. static Future fromContext(DartdocGeneratorOptionContext context, + // TODO(srawlins): Remove this option, as runtime templates are no longer + // supported. {bool forceRuntimeTemplates = false}) async { - var templatesDir = context.templatesDir; - if (templatesDir != null) { - return RuntimeTemplates._create( - context.resourceProvider.getFolder(templatesDir), - resourceProvider: context.resourceProvider); - } else if (forceRuntimeTemplates) { + if (forceRuntimeTemplates) { var directory = await context.resourceProvider .getResourceFolder('package:dartdoc/templates'); return RuntimeTemplates._create(directory, diff --git a/test/options_test.dart b/test/options_test.dart index 0879ececd3..525672679e 100644 --- a/test/options_test.dart +++ b/test/options_test.dart @@ -438,88 +438,6 @@ class C1 {} package.documentedCategoriesSorted.map((c) => c.name), equals(['One'])); } - void - test_templatesDirOption_referencingANonExistentDirectory_resultsInDartdocFailure() async { - await createPackage( - libFiles: [ - d.file('library_1.dart', ''' -library library_1; -class Foo {} -'''), - ], - ); - expect( - () => buildDartdoc(additionalArguments: ['--templates-dir', 'bad']), - throwsA(const TypeMatcher().having( - (f) => f.message, - 'message', - startsWith( - 'Argument --templates-dir, set to bad, resolves to missing path'), - ))); - } - - void test_templatesDirOption_specifiesTheTemplatesToUse() async { - await createPackage( - libFiles: [ - d.file('library_1.dart', ''' -library library_1; -class Foo {} -'''), - ], - files: [ - d.dir('templates', [ - d.file('_sidebar_for_container.html', 'EMPTY'), - d.file('_sidebar_for_library.html', 'EMPTY'), - d.file('404error.html', 'EMPTY'), - d.file('category.html', 'EMPTY'), - d.file('class.html', 'CLASS FILE'), - d.file('constructor.html', 'EMPTY'), - d.file('enum.html', 'EMPTY'), - d.file('extension.html', 'EMPTY'), - d.file('function.html', 'EMPTY'), - d.file('index.html', 'EMPTY'), - d.file('library.html', 'EMPTY'), - d.file('method.html', 'EMPTY'), - d.file('mixin.html', 'EMPTY'), - d.file('property.html', 'EMPTY'), - d.file('top_level_property.html', 'EMPTY'), - d.file('typedef.html', 'EMPTY'), - d.file('search.html', 'EMPTY'), - ]), - ], - ); - var customTemplatesDir = path.join(packagePath, 'templates'); - var dartdoc = await buildDartdoc( - additionalArguments: ['--templates-dir', customTemplatesDir]); - await dartdoc.generateDocsBase(); - final indexContent = resourceProvider - .getFile( - path.joinAll([packagePath, 'doc', 'library_1', 'Foo-class.html'])) - .readAsStringSync(); - expect(indexContent, contains('CLASS FILE')); - } - - void - test_templatesDirOptionReferencingAnEmptyDirectory_resultsInDartdocFailure() async { - await createPackage( - libFiles: [ - d.file('library_1.dart', ''' -library library_1; -class Foo {} -'''), - ], - ); - var customTemplatesDir = resourceProvider - .newFolder(resourceProvider.pathContext - .canonicalize(resourceProvider.convertPath('/custom_templates'))) - .path; - expect( - () => buildDartdoc( - additionalArguments: ['--templates-dir', customTemplatesDir]), - throwsA(const TypeMatcher().having((f) => f.message, - 'message', startsWith('Missing required template file')))); - } - void test_emptyPackage() async { await createPackage(); await (await buildDartdoc()).generateDocs(); From 50fffd8ff2846b89ed311c304ad6c6900167f0a9 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:29:22 -0700 Subject: [PATCH 2/5] Bump to 9.0.0-dev --- CHANGELOG.md | 4 ++++ dartdoc_options.yaml | 2 +- lib/src/version.dart | 2 +- pubspec.yaml | 2 +- testing/test_package/lib/src/nodocme.dart | 11 ----------- 5 files changed, 7 insertions(+), 14 deletions(-) delete mode 100644 testing/test_package/lib/src/nodocme.dart diff --git a/CHANGELOG.md b/CHANGELOG.md index ecbb21a51c..4d856430fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 9.0.0-dev + +* Remove the deprecated `nodoc` option. + ## 8.3.3 * Require Dart 3.6 or later. diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml index 01513eea5a..be4c175df8 100644 --- a/dartdoc_options.yaml +++ b/dartdoc_options.yaml @@ -1,4 +1,4 @@ dartdoc: linkToSource: root: '.' - uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.3.3/%f%#L%l%' + uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v9.0.0-dev/%f%#L%l%' diff --git a/lib/src/version.dart b/lib/src/version.dart index dfdd62ad95..15a50c49dc 100644 --- a/lib/src/version.dart +++ b/lib/src/version.dart @@ -1 +1 @@ -const packageVersion = '8.3.3'; +const packageVersion = '9.0.0-dev'; diff --git a/pubspec.yaml b/pubspec.yaml index c951c220f7..a4e6d636ba 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,5 +1,5 @@ name: dartdoc -version: 8.3.3 +version: 9.0.0-dev description: A non-interactive HTML documentation generator for Dart source code. repository: https://github.com/dart-lang/dartdoc diff --git a/testing/test_package/lib/src/nodocme.dart b/testing/test_package/lib/src/nodocme.dart deleted file mode 100644 index 707a399fb6..0000000000 --- a/testing/test_package/lib/src/nodocme.dart +++ /dev/null @@ -1,11 +0,0 @@ -/// -/// The library nodocme should never have any members documented, even if -/// reexported, due to dartdoc_options.yaml in the package root. -/// - -library nodocme; - -/// I should not appear in documentation. -class NodocMeImplementation {} - -class MeNeitherEvenWithoutADocComment {} From 941bd7003f726cb0297f007c1aaaab249942e318 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:36:47 -0700 Subject: [PATCH 3/5] changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d856430fd..7c81430e22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ ## 9.0.0-dev -* Remove the deprecated `nodoc` option. +* Remove the deprecated `templates-dir` option. ## 8.3.3 From fb45ca65cbba459f9c307f56392141121d63baf0 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:40:41 -0700 Subject: [PATCH 4/5] whoops --- lib/src/generator/generator_frontend.dart | 9 --------- testing/test_package/lib/src/nodocme.dart | 10 ++++++++++ 2 files changed, 10 insertions(+), 9 deletions(-) create mode 100644 testing/test_package/lib/src/nodocme.dart diff --git a/lib/src/generator/generator_frontend.dart b/lib/src/generator/generator_frontend.dart index 49caad3250..33f23f8c66 100644 --- a/lib/src/generator/generator_frontend.dart +++ b/lib/src/generator/generator_frontend.dart @@ -4,7 +4,6 @@ import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/generator/generator_backend.dart'; -import 'package:dartdoc/src/generator/templates.dart'; import 'package:dartdoc/src/logging.dart'; import 'package:dartdoc/src/model/model.dart'; import 'package:dartdoc/src/model_utils.dart'; @@ -20,14 +19,6 @@ class GeneratorFrontEnd implements Generator { @override Future generate(PackageGraph? packageGraph) async { - if (_generatorBackend.templates is RuntimeTemplates) { - packageGraph?.defaultPackage.warn( - PackageWarning.deprecated, - message: "The '--templates-dir' option is deprecated, and will soon no " - 'longer be supported.', - ); - } - await _generatorBackend.generateAdditionalFiles(); if (packageGraph == null) { diff --git a/testing/test_package/lib/src/nodocme.dart b/testing/test_package/lib/src/nodocme.dart new file mode 100644 index 0000000000..a7fd32293b --- /dev/null +++ b/testing/test_package/lib/src/nodocme.dart @@ -0,0 +1,10 @@ +/// +/// The library nodocme should never have any members documented, even if +/// reexported, due to dartdoc_options.yaml in the package root. +/// +library nodocme; + +/// I should not appear in documentation. +class NodocMeImplementation {} + +class MeNeitherEvenWithoutADocComment {} From 9cb1035b1f2a4ab69240ddb8ac6616ea3858469d Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:41:09 -0700 Subject: [PATCH 5/5] whoops --- testing/test_package/lib/src/nodocme.dart | 1 + 1 file changed, 1 insertion(+) diff --git a/testing/test_package/lib/src/nodocme.dart b/testing/test_package/lib/src/nodocme.dart index a7fd32293b..707a399fb6 100644 --- a/testing/test_package/lib/src/nodocme.dart +++ b/testing/test_package/lib/src/nodocme.dart @@ -2,6 +2,7 @@ /// The library nodocme should never have any members documented, even if /// reexported, due to dartdoc_options.yaml in the package root. /// + library nodocme; /// I should not appear in documentation.