Determine file extensions on a per-package basis (#2134)

* Extract file extensions to a new renderer

* Determine file type based on documentation location

* Use config instead of a new renderer

Author: jdkoren

lib/src/dartdoc_options.dart

@@ -1421,6 +1421,9 @@ class DartdocOptionContext extends DartdocOptionContextBase
   bool isPackageExcluded(String name) =>
       excludePackages.any((pattern) => name == pattern);
 
+  /// Output format, e.g. 'html', 'md'
+  String get format => optionSet['format'].valueAt(context);
+
   // TODO(jdkoren): temporary while we confirm href base behavior doesn't break important clients
   bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
 }
@@ -1633,6 +1636,8 @@ Future<List<DartdocOption>> createDartdocOptions() async {
             'pages, and please file an issue on Github.',
         negatable: false,
         hide: true),
+    // TODO(jdkoren): Unhide when we have good support for another format.
+    DartdocOptionArgOnly<String>('format', 'html', hide: true),
     // TODO(jcollins-g): refactor so there is a single static "create" for
     // each DartdocOptionContext that traverses the inheritance tree itself.
   ]

lib/src/generator.dart

@@ -56,9 +56,6 @@ mixin GeneratorContext on DartdocOptionContextBase {
 
   String get templatesDir => optionSet['templatesDir'].valueAt(context);
 
-  /// Output format, e.g. 'html', 'md'
-  String get format => optionSet['format'].valueAt(context);
-
   // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.
   bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
 }
@@ -141,7 +138,5 @@ Future<List<DartdocOption>> createGeneratorOptions() async {
             '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(jdkoren): Unhide when we have good support for another format.
-    DartdocOptionArgOnly<String>('format', 'html', hide: true),
   ];
 }

lib/src/model/category.dart

@@ -120,14 +120,16 @@ class Category extends Nameable
   @override
   String get fullyQualifiedName => name;
 
-  String get filePath => 'topics/${name}-topic.html';
+  String get fileType => package.fileType;
+
+  String get filePath => 'topics/$name-topic.$fileType';
 
   @override
   String get href => isCanonical ? '${package.baseHref}$filePath' : null;
 
-  String get categorization => _renderer.renderCategoryLabel(this);
+  String get categorization => _categoryRenderer.renderCategoryLabel(this);
 
-  String get linkedName => _renderer.renderLinkedName(this);
+  String get linkedName => _categoryRenderer.renderLinkedName(this);
 
   int _categoryIndex;
 
@@ -199,6 +201,6 @@ class Category extends Nameable
   @override
   Iterable<Typedef> get typedefs => _typedefs;
 
-  CategoryRenderer get _renderer =>
+  CategoryRenderer get _categoryRenderer =>
       packageGraph.rendererFactory.categoryRenderer;
 }

lib/src/model/class.dart

@@ -184,7 +184,7 @@ class Class extends Container
   ModelElement get enclosingElement => library;
 
   @override
-  String get fileName => "${name}-class.html";
+  String get fileName => '$name-class.$fileType';
 
   @override
   String get filePath => '${library.dirName}/$fileName';

lib/src/model/field.dart

@@ -156,7 +156,7 @@ class Field extends ModelElement
   FieldElement get field => (element as FieldElement);
 
   @override
-  String get fileName => isConst ? '$name-constant.html' : '$name.html';
+  String get fileName => '${isConst ? '$name-constant' : name}.$fileType';
 
   String _sourceCode;
 

lib/src/model/library.dart

@@ -375,7 +375,7 @@ class Library extends ModelElement with Categorization, TopLevelContainer {
   }
 
   @override
-  String get fileName => '$dirName-library.html';
+  String get fileName => '$dirName-library.$fileType';
 
   @override
   String get filePath => '${library.dirName}/$fileName';

lib/src/model/mixin.dart

@@ -64,7 +64,7 @@ class Mixin extends Class {
   bool get hasModifiers => super.hasModifiers || hasPublicSuperclassConstraints;
 
   @override
-  String get fileName => "${name}-mixin.html";
+  String get fileName => '$name-mixin.$fileType';
 
   @override
   String get kind => 'mixin';

lib/src/model/model_element.dart

@@ -787,7 +787,9 @@ abstract class ModelElement extends Canonicalization
     return '';
   }
 
-  String get fileName => "${name}.html";
+  String get fileName => '$name.$fileType';
+
+  String get fileType => package.fileType;
 
   String get filePath;
 

lib/src/model/operator.dart

@@ -42,10 +42,9 @@ class Operator extends Method {
   String get fileName {
     var actualName = super.name;
     if (friendlyNames.containsKey(actualName)) {
-      return "operator_${friendlyNames[actualName]}.html";
-    } else {
-      return '$actualName.html';
+      actualName = "operator_${friendlyNames[actualName]}";
     }
+    return '$actualName.$fileType';
   }
 
   @override

lib/src/model/package.dart

@@ -181,7 +181,19 @@ class Package extends LibraryContainer
   @override
   String get enclosingName => packageGraph.defaultPackageName;
 
-  String get filePath => 'index.html';
+  String get filePath => 'index.$fileType';
+
+  String get fileType {
+    // TODO(jdkoren): Provide a way to determine file type of a remote package's
+    // docs. Perhaps make this configurable through dartdoc options.
+    // In theory, a remote package could be documented in any supported format.
+    // In practice, devs depend on Dart, Flutter, and/or packages fetched
+    // from pub.dev, and we know that all of those use html docs.
+    if (package.documentedWhere == DocumentLocation.remote) {
+      return 'html';
+    }
+    return config.format;
+  }
 
   @override
   String get fullyQualifiedName => 'package:$name';

lib/src/model/top_level_variable.dart

@@ -85,7 +85,7 @@ class TopLevelVariable extends ModelElement
   }
 
   @override
-  String get fileName => isConst ? '$name-constant.html' : '$name.html';
+  String get fileName => '${isConst ? '$name-constant' : name}.$fileType';
 
   @override
   DefinedElementType get modelType => super.modelType;

lib/src/render/file_type_renderer.dart

@@ -0,0 +1,12 @@
+// Copyright (c) 2020, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+abstract class FileTypeRenderer {
+  String get fileType;
+}
+
+class HtmlFileTypeRenderer extends FileTypeRenderer {
+  @override
+  String get fileType => 'html';
+}