From 51564774bc377f0e5ea15a0ab8949fd5b471ad15 Mon Sep 17 00:00:00 2001
From: Kallen Tu <kallentu@google.com>
Date: Wed, 21 Feb 2024 22:22:49 +0000
Subject: [PATCH 1/2] Deprecate  option.

---
 CHANGELOG.md                     |  1 +
 lib/src/dartdoc_options.dart     |  1 +
 lib/src/generator/generator.dart | 30 +++++++++++++++++-------------
 3 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c656d7918..949178d343 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart
index 1037f68e6f..f98b542255 100644
--- a/lib/src/dartdoc_options.dart
+++ b/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.
diff --git a/lib/src/generator/generator.dart b/lib/src/generator/generator.dart
index 6e287bbbf7..d251536b41 100644
--- a/lib/src/generator/generator.dart
+++ b/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).',
+    ),
   ];
 }

From 69a3fbe5a7a81a912f378dd07c44516374d7f844 Mon Sep 17 00:00:00 2001
From: Kallen Tu <kallentu@google.com>
Date: Fri, 23 Feb 2024 15:41:31 +0000
Subject: [PATCH 2/2] Add deprecation warning.

---
 lib/src/generator/generator_frontend.dart | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/src/generator/generator_frontend.dart b/lib/src/generator/generator_frontend.dart
index 1f744beeb6..3f361eaa53 100644
--- a/lib/src/generator/generator_frontend.dart
+++ b/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);