Deprecate --templates-dir option. (#3667)

* Deprecate  option.

* Add deprecation warning.

Author: kallentu

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 8.0.6-wip
 
 * Add troubleshooting information when the sidebars failed to load.
+* Deprecate the `--templates-dir` option.
 
 ## 8.0.5
 

lib/src/dartdoc_options.dart

@@ -1409,6 +1409,7 @@ 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.

lib/src/generator/generator.dart

@@ -82,18 +82,22 @@ List<DartdocOption> 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.'),
-    DartdocOptionArgOnly<String?>('templatesDir', null, resourceProvider,
-        optionIs: OptionKind.dir,
-        mustExist: true,
-        hide: true,
-        help:
-            '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).'),
+    // TODO(kallentu): Remove --templates-dir completely.
+    DartdocOptionArgOnly<String?>(
+      '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).',
+    ),
   ];
 }

lib/src/generator/generator_frontend.dart

@@ -4,6 +4,7 @@
 
 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';
@@ -19,6 +20,14 @@ class GeneratorFrontEnd implements Generator {
 
   @override
   Future<void> 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.',
+      );
+    }
+
     var indexElements = packageGraph == null
         ? const <Indexable>[]
         : _generateDocs(packageGraph);