Improves the default template for TypeScript documentation

src/Microsoft.DocAsCode.Build.UniversalReference/BuildOutputs/ApiBuildOutput.cs

@@ -27,6 +27,10 @@ public class ApiBuildOutput
         [JsonProperty(Constants.PropertyName.Parent)]
         public List<ApiLanguageValuePair<ApiNames>> Parent { get; set; }
 
+        [YamlMember(Alias = "package")]
+        [JsonProperty("package")]
+        public List<ApiLanguageValuePair<ApiNames>> Package { get; set; }
+
         [YamlMember(Alias = Constants.PropertyName.Children)]
         [JsonProperty(Constants.PropertyName.Children)]
         public List<ApiLanguageValuePair<List<ApiBuildOutput>>> Children { get; set; }
@@ -113,7 +117,7 @@ public class ApiBuildOutput
 
         [YamlMember(Alias = Constants.PropertyName.Inheritance)]
         [JsonProperty(Constants.PropertyName.Inheritance)]
-        public List<ApiLanguageValuePair<List<ApiInheritanceTreeBuildOutput>>> Inheritance { get; set; }
+        public List<ApiLanguageValuePairWithLevel<List<ApiInheritanceTreeBuildOutput>>> Inheritance { get; set; }
 
         [YamlMember(Alias = Constants.PropertyName.DerivedClasses)]
         [JsonProperty(Constants.PropertyName.DerivedClasses)]

src/Microsoft.DocAsCode.Build.UniversalReference/BuildOutputs/ApiInheritanceTreeBuildOutput.cs

@@ -23,6 +23,10 @@ public class ApiInheritanceTreeBuildOutput
         [JsonProperty(Constants.PropertyName.Inheritance)]
         public List<ApiInheritanceTreeBuildOutput> Inheritance { get; set; }
 
+        [YamlMember(Alias = "level")]
+        [JsonProperty("level")]
+        public int Level { get; set; }
+
         [ExtensibleMember]
         [JsonExtensionData]
         public Dictionary<string, object> Metadata { get; set; } = new Dictionary<string, object>();

src/Microsoft.DocAsCode.Build.UniversalReference/BuildOutputs/ApiLanguageValuePairWithLevel.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace Microsoft.DocAsCode.Build.UniversalReference
+{
+    using System;
+
+    using Newtonsoft.Json;
+    using YamlDotNet.Serialization;
+
+    [Serializable]
+    public class ApiLanguageValuePairWithLevel<T> : ApiLanguageValuePair<T>
+    {
+        [YamlMember(Alias = "level")]
+        [JsonProperty("level")]
+        public int Level { get; set; }
+    }
+}

src/Microsoft.DocAsCode.Build.UniversalReference/ModelConverter/ApiBuildOutputProfile.cs

@@ -21,6 +21,7 @@ public ApiBuildOutputProfile(
                 .ForMember(dest => dest.Metadata, opt => opt.ResolveUsing(new ApiBuildOutputMetadataResolver(metadata)))
                 .ForMember(dest => dest.Children, opt => opt.Ignore())
                 .ForMember(dest => dest.Parent, opt => opt.Ignore())
+                .ForMember(dest => dest.Package, opt => opt.Ignore())
                 .ForMember(dest => dest.NamespaceName, opt => opt.Ignore())
                 .ForMember(dest => dest.Overridden, opt => opt.Ignore())
                 .ForMember(dest => dest.Name, opt => opt.Ignore())
@@ -41,6 +42,7 @@ public ApiBuildOutputProfile(
                 .AfterMap((src, dest) =>
                 {
                     dest.Parent = ModelConverter.ToApiListInDevLangsResolvingApiNames(src.Parent, src.ParentInDevLangs, supportedLanguages, references);
+                    dest.Package = ModelConverter.ToApiListInDevLangsResolvingApiNames(src.Package, src.PackageInDevLangs, supportedLanguages, references);
                     dest.NamespaceName = ModelConverter.ToApiListInDevLangsResolvingApiNames(src.NamespaceName, src.NamespaceNameInDevLangs, supportedLanguages, references);
                     dest.Overridden = ModelConverter.ToApiListInDevLangsResolvingApiNames(src.Overridden, src.OverriddenInDevLangs, supportedLanguages, references);
 
@@ -57,8 +59,7 @@ public ApiBuildOutputProfile(
                     dest.DerivedClasses = ModelConverter.ToApiListInDevLangsResolvingApiNames(src.DerivedClasses, src.DerivedClassesInDevLangs, supportedLanguages, references);
 
                     dest.Exceptions = ModelConverter.ToApiListInDevlangsResolvingApiNames(src.Exceptions, src.ExceptionsInDevLangs, supportedLanguages, references);
-
-                    dest.Inheritance = ModelConverter.ToApiListInDevlangsResolvingApiNames(src.Inheritance, src.InheritanceInDevLangs, supportedLanguages, references);
+                    dest.Inheritance = ModelConverter.ToApiListInDevLangsResolvingApiNames(src.Inheritance, src.InheritanceInDevLangs, supportedLanguages, references);
                 });
             CreateMap<ReferenceViewModel, ApiBuildOutput>()
                 .ForMember(dest => dest.Metadata, opt => opt.MapFrom(src => src.Additional))
@@ -89,6 +90,7 @@ public ApiBuildOutputProfile(
                 .ForMember(dest => dest.ExtensionMethods, opt => opt.Ignore())
                 .ForMember(dest => dest.Conceptual, opt => opt.Ignore())
                 .ForMember(dest => dest.Platform, opt => opt.Ignore())
+                .ForMember(dest => dest.Package, opt => opt.Ignore())
                 .AfterMap((src, dest) =>
                 {
                     dest.Name = ModelConverter.ToApiListInDevLangs(src.Name, src.NameInDevLangs, supportedLanguages);
@@ -142,7 +144,8 @@ public ApiBuildOutputProfile(
                     opt.Condition(src => src.LinkType == LinkType.HRef);
                     opt.ResolveUsing(new ApiHrefLinkInfoBuildOutputUrlResolver());
                 });
-            CreateMap<InheritanceTree, ApiInheritanceTreeBuildOutput>();
+            CreateMap<InheritanceTree, ApiInheritanceTreeBuildOutput>()
+                .ForMember(dest => dest.Level, opt => opt.Ignore());
         }
     }
 }

src/Microsoft.DocAsCode.Build.UniversalReference/ModelConverter/ModelConverter.cs

@@ -116,7 +116,7 @@ public static List<ApiLanguageValuePair<ApiNames>> ToApiListInDevLangsResolvingA
                 }).ToList();
         }
 
-        public static List<ApiLanguageValuePair<List<ApiInheritanceTreeBuildOutput>>> ToApiListInDevlangsResolvingApiNames(List<InheritanceTree> defaultValue, SortedList<string, List<InheritanceTree>> values, string[] supportedLanguages, IReadOnlyDictionary<string, ApiNames> references)
+        public static List<ApiLanguageValuePairWithLevel<List<ApiInheritanceTreeBuildOutput>>> ToApiListInDevLangsResolvingApiNames(List<InheritanceTree> defaultValue, SortedList<string, List<InheritanceTree>> values, string[] supportedLanguages, IReadOnlyDictionary<string, ApiNames> references)
         {
             if (defaultValue == null || supportedLanguages == null || supportedLanguages.Length == 0)
             {
@@ -125,10 +125,12 @@ public static List<ApiLanguageValuePair<List<ApiInheritanceTreeBuildOutput>>> To
             return ToApiListInDevLangs(defaultValue, values, supportedLanguages)
                 ?.Select(pair =>
                 {
-                    return new ApiLanguageValuePair<List<ApiInheritanceTreeBuildOutput>>
+                    var maxDepth = CalculateInheritanceDepth(pair.Value);
+                    return new ApiLanguageValuePairWithLevel<List<ApiInheritanceTreeBuildOutput>>
                     {
                         Language = pair.Language,
-                        Value = pair.Value.Select(item => ResolveInheritanceTree(item, supportedLanguages, references)).ToList()
+                        Value = pair.Value.Select(item => ResolveInheritanceTree(item, supportedLanguages, references, 0, maxDepth)).ToList(),
+                        Level = maxDepth
                     };
                 }).ToList();
         }
@@ -261,12 +263,23 @@ public static string GetXref(string uid, string text = null, string alt = null)
             return result;
         }
 
-        private static ApiInheritanceTreeBuildOutput ResolveInheritanceTree(InheritanceTree tree, string[] supportedLanguages, IReadOnlyDictionary<string, ApiNames> references)
+        private static int CalculateInheritanceDepth(InheritanceTree tree)
+        {
+            return CalculateInheritanceDepth(tree.Inheritance) + 1;
+        }
+
+        private static int CalculateInheritanceDepth(List<InheritanceTree> trees)
+        {
+            return trees == null ? 0 : trees.Max(CalculateInheritanceDepth);
+        }
+
+        private static ApiInheritanceTreeBuildOutput ResolveInheritanceTree(InheritanceTree tree, string[] supportedLanguages, IReadOnlyDictionary<string, ApiNames> references, int depth, int maxDepth)
         {
             return new ApiInheritanceTreeBuildOutput
             {
                 Type = ResolveApiNames(tree.Type, supportedLanguages, references),
-                Inheritance = tree.Inheritance?.Select(item => ResolveInheritanceTree(item, supportedLanguages, references)).ToList(),
+                Inheritance = tree.Inheritance?.Select(item => ResolveInheritanceTree(item, supportedLanguages, references, depth + 1, maxDepth)).ToList(),
+                Level = maxDepth - depth - 1,
                 Metadata = tree.Metadata
             };
         }

src/Microsoft.DocAsCode.DataContracts.UniversalReference/ItemViewModel.cs

@@ -47,6 +47,15 @@ public class ItemViewModel : IOverwriteDocumentViewModel
         [JsonIgnore]
         public SortedList<string, string> ParentInDevLangs { get; set; } = new SortedList<string, string>();
 
+        [YamlMember(Alias = "package")]
+        [JsonProperty("package")]
+        [UniqueIdentityReference]
+        public string Package { get; set; }
+
+        [ExtensibleMember("package" + Constants.PrefixSeparator)]
+        [JsonIgnore]
+        public SortedList<string, string> PackageInDevLangs { get; set; } = new SortedList<string, string>();
+
         [YamlMember(Alias = Constants.PropertyName.Children)]
         [MergeOption(MergeOption.Ignore)] // todo : merge more children
         [JsonProperty(Constants.PropertyName.Children)]
@@ -308,6 +317,7 @@ public class ItemViewModel : IOverwriteDocumentViewModel
             CompositeDictionary
                 .CreateBuilder()
                 .Add(Constants.ExtensionMemberPrefix.Parent, ParentInDevLangs, JTokenConverter.Convert<string>)
+                .Add("package" + Constants.PrefixSeparator, PackageInDevLangs, JTokenConverter.Convert<string>)
                 .Add(Constants.ExtensionMemberPrefix.Children, ChildrenInDevLangs, JTokenConverter.Convert<List<string>>)
                 .Add(Constants.ExtensionMemberPrefix.Source, SourceInDevLangs, JTokenConverter.Convert<SourceDetail>)
                 .Add(Constants.ExtensionMemberPrefix.Namespace, NamespaceNameInDevLangs, JTokenConverter.Convert<string>)

src/docfx.website.themes/common/ManagedReference.common.js

@@ -20,6 +20,7 @@ exports.transform = function (model) {
       case 'namespace':
         model.isNamespace = true;
         if (model.children) groupChildren(model, namespaceCategory);
+        model[getTypePropertyName(model.type)] = true;
         break;
       case 'class':
       case 'interface':
@@ -158,6 +159,7 @@ function getDefinition(type) {
 
 function getDefinitions(category) {
   var namespaceItems = {
+    "namespace":    { inNamespace: true,    typePropertyName: "inNamespace",    id: "namespaces" },
     "class":        { inClass: true,        typePropertyName: "inClass",        id: "classes" },
     "struct":       { inStruct: true,       typePropertyName: "inStruct",       id: "structs" },
     "interface":    { inInterface: true,    typePropertyName: "inInterface",    id: "interfaces" },

src/docfx.website.themes/common/UniversalReference.common.js

@@ -9,18 +9,20 @@ exports.transform = function (model) {
 
   handleItem(model, model._gitContribute, model._gitUrlPattern);
   if (model.children) {
-    normalizeChildren(model.children).forEach(function (item) {
+    normalizeLanguageValuePairs(model.children).forEach(function (item) {
       handleItem(item, model._gitContribute, model._gitUrlPattern);
     });
   };
 
   if (model.type) {
     switch (model.type.toLowerCase()) {
+      // packages and namespaces are both containers for other elements
+      case 'package':
       case 'namespace':
         model.isNamespace = true;
         if (model.children) groupChildren(model, namespaceCategory);
+        model[getTypePropertyName(model.type)] = true;
         break;
-      case 'package':
       case 'class':
       case 'interface':
       case 'struct':
@@ -49,7 +51,7 @@ exports.getBookmarks = function (model, ignoreChildren)  {
 
   if (typeof ignoreChildren == 'undefined' || ignoreChildren === false) {
     if (model.children) {
-      normalizeChildren(model.children).forEach(function (item) {
+      normalizeLanguageValuePairs(model.children).forEach(function (item) {
         bookmarks[item.uid] = common.getHtmlId(item.uid);
         if (item.overload && item.overload.uid) {
           bookmarks[item.overload.uid] = common.getHtmlId(item.overload.uid);
@@ -75,6 +77,11 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
   vm.syntax = vm.syntax || null;
   vm.implements = vm.implements || null;
   vm.example = vm.example || null;
+  vm.inheritance = vm.inheritance || null;
+  if (vm.inheritance) {
+    normalizeLanguageValuePairs(vm.inheritance).forEach(handleInheritance);
+  }
+
   common.processSeeAlso(vm);
 
   // id is used as default template's bookmark
@@ -98,6 +105,14 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
   }
 }
 
+function handleInheritance(tree) {
+  tree.type = tree.type || null;
+  tree.inheritance = tree.inheritance || null;
+  if (tree.inheritance) {
+    tree.inheritance.forEach(handleInheritance);
+  }
+}
+
 function joinType(parameter) {
   // change type in syntax from array to string
   var joinTypeProperty = function (type, key) {
@@ -165,7 +180,7 @@ function groupChildren(model, category, typeChildrenItems) {
   }
   var grouped = {};
 
-  normalizeChildren(model.children).forEach(function (c) {
+  normalizeLanguageValuePairs(model.children).forEach(function (c) {
     if (c.isEii) {
       var type = "eii";
     } else {
@@ -189,6 +204,14 @@ function groupChildren(model, category, typeChildrenItems) {
       c.syntax.eventType = c.syntax.return;
       c.syntax.return = undefined;
     }
+    if (type === "variable" && c.syntax) {
+      c.syntax.variableValue = c.syntax.return;
+      c.syntax.return = undefined;
+    }
+    if (type === "typealias" && c.syntax) {
+      c.syntax.typeAliasType = c.syntax.return;
+      c.syntax.return = undefined;
+    }
     grouped[type].push(c);
   })
 
@@ -253,12 +276,16 @@ function getDefinition(type) {
 
 function getDefinitions(category) {
   var namespaceItems = {
+    "package":      { inPackage: true,      typePropertyName: "inPackage",      id: "packages" },
+    "namespace":    { inNamespace: true,    typePropertyName: "inNamespace",    id: "namespaces" },
     "class":        { inClass: true,        typePropertyName: "inClass",        id: "classes" },
     "struct":       { inStruct: true,       typePropertyName: "inStruct",       id: "structs" },
     "interface":    { inInterface: true,    typePropertyName: "inInterface",    id: "interfaces" },
     "enum":         { inEnum: true,         typePropertyName: "inEnum",         id: "enums" },
     "delegate":     { inDelegate: true,     typePropertyName: "inDelegate",     id: "delegates" },
-    "package":      { inDelegate: true,     typePropertyName: "inPackage",      id: "packages" }
+    "function":     { inFunction: true,     typePropertyName: "inFunction",     id: "functions",    isEmbedded: true },
+    "variable":     { inVariable: true,     typePropertyName: "inVariable",     id: "variables",    isEmbedded: true },
+    "typealias":    { inTypeAlias: true,    typePropertyName: "inTypeAlias",    id: "typealiases",  isEmbedded: true },
   };
   var classItems = {
     "constructor":  { inConstructor: true,  typePropertyName: "inConstructor",  id: "constructors" },
@@ -268,8 +295,8 @@ function getDefinitions(category) {
     "event":        { inEvent: true,        typePropertyName: "inEvent",        id: "events" },
     "operator":     { inOperator: true,     typePropertyName: "inOperator",     id: "operators" },
     "eii":          { inEii: true,          typePropertyName: "inEii",          id: "eii" },
-    "function":     { inFunction: true,     typePropertyName: "inFunction",     id: "functions"},
-    "member":       { inMember: true,       typePropertyName: "inMember",       id: "members"}
+    "member":       { inMember: true,       typePropertyName: "inMember",       id: "members"},
+    "function":     { inFunction: true,     typePropertyName: "inFunction",     id: "functions" }
   };
   if (category === 'class') {
     return classItems;
@@ -281,9 +308,9 @@ function getDefinitions(category) {
   return undefined;
 }
 
-function normalizeChildren(children) {
-  if (children[0] && children[0].lang && children[0].value) {
-    return children[0].value;
+function normalizeLanguageValuePairs(list) {
+  if (list[0] && list[0].lang && list[0].value) {
+    return list[0].value;
   }
-  return children;
-}
+  return list;
+}

src/docfx.website.themes/common/partials/namespaceSubtitle.tmpl.partial

@@ -1,4 +1,9 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+{{^isNamespace}}
+{{#inNamespace}}
+{{__global.namespacesInSubtitle}}
+{{/inNamespace}}
+{{/isNamespace}}
 {{#inClass}}
 {{__global.classesInSubtitle}}
 {{/inClass}}
@@ -13,4 +18,13 @@
 {{/inEnum}}
 {{#inDelegate}}
 {{__global.delegatesInSubtitle}}
-{{/inDelegate}}
+{{/inDelegate}}
+{{#inFunction}}
+{{__global.functionsInSubtitle}}
+{{/inFunction}}
+{{#inVariable}}
+{{__global.variablesInSubtitle}}
+{{/inVariable}}
+{{#inTypeAlias}}
+{{__global.typeAliasesInSubtitle}}
+{{/inTypeAlias}}

src/docfx.website.themes/default/UniversalReference.html.primary.tmpl

@@ -2,7 +2,7 @@
 {{!master(layout/_master.tmpl)}}
 
 {{#isNamespace}}
-  {{>partials/namespace}}
+  {{>partials/uref/namespace}}
 {{/isNamespace}}
 {{#isClass}}
   {{>partials/uref/class}}

src/docfx.website.themes/default/partials/title.tmpl.partial

@@ -1,7 +1,10 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
-{{#isNamespace}}
+{{#inPackage}}
+Package {{name.0.value}}
+{{/inPackage}}
+{{#inNamespace}}
 Namespace {{name.0.value}}
-{{/isNamespace}}
+{{/inNamespace}}
 {{#inClass}}
 Class {{name.0.value}}
 {{/inClass}}
@@ -38,6 +41,9 @@ Operator {{name.0.value}}
 {{#inEii}}
 Explict Interface Implementation {{name.0.value}}
 {{/inEii}}
-{{#inPackage}}
-Package {{name.0.value}}
-{{/inPackage}}
+{{#inVariable}}
+Variable {{name.0.value}}
+{{/inVariable}}
+{{#inTypeAlias}}
+Type Alias {{name.0.value}}
+{{/inTypeAlias}}