Cleanup templates and fix #49

fsprojects · Nov 27, 2013 · addaaec · addaaec
1 parent 5cc1af9
commit addaaec
Show file tree

Hide file tree

Showing 19 changed files with 503 additions and 134 deletions.
diff --git a/FSharp.Formatting.nunit b/FSharp.Formatting.nunit
@@ -2,6 +2,9 @@
   <Settings activeconfig="Debug" />
   <Config name="Debug" binpathtype="Auto">
     <assembly path="tests\FSharp.CodeFormat.Tests\bin\Debug\FSharp.CodeFormat.Tests.dll" />
+    <assembly path="tests\FSharp.Literate.Tests\bin\Debug\FSharp.Literate.Tests.dll" />
+    <assembly path="tests\FSharp.Markdown.Tests\bin\Debug\FSharp.Markdown.Tests.dll" />
+    <assembly path="tests\FSharp.MetadataFormat.Tests\bin\Debug\FSharp.MetadataFormat.Tests.dll" />
   </Config>
   <Config name="Release" binpathtype="Auto" />
 </NUnitProject>
diff --git a/FSharp.Formatting.sln b/FSharp.Formatting.sln
@@ -23,7 +23,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "nuget", "nuget", "{5C565F18
 		.nuget\NuGet.targets = .nuget\NuGet.targets
 	EndProjectSection
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Literate", "Literate", "{57C28077-FFFE-4F57-B31D-344A9288076B}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "literate", "literate", "{57C28077-FFFE-4F57-B31D-344A9288076B}"
 	ProjectSection(SolutionItems) = preProject
 		misc\literate\build.fsx = misc\literate\build.fsx
 		misc\literate\demo.fsx = misc\literate\demo.fsx
@@ -61,6 +61,21 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tools", "tools", "{BEE70727
 		docs\tools\template.html = docs\tools\template.html
 	EndProjectSection
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "templates", "templates", "{D0550510-0DCE-4B40-B4FB-091668E1C5FD}"
+	ProjectSection(SolutionItems) = preProject
+		misc\templates\docpage.cshtml = misc\templates\docpage.cshtml
+		misc\templates\template.cshtml = misc\templates\template.cshtml
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "reference", "reference", "{917A4F64-8304-4228-B29A-E2FB474B761B}"
+	ProjectSection(SolutionItems) = preProject
+		misc\templates\reference\module.cshtml = misc\templates\reference\module.cshtml
+		misc\templates\reference\namespaces.cshtml = misc\templates\reference\namespaces.cshtml
+		misc\templates\reference\part-members.cshtml = misc\templates\reference\part-members.cshtml
+		misc\templates\reference\part-nested.cshtml = misc\templates\reference\part-nested.cshtml
+		misc\templates\reference\type.cshtml = misc\templates\reference\type.cshtml
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -124,5 +139,6 @@ Global
 		{71885AB0-0A46-4FC8-AEDF-F2DC4BEB0E67} = {312E452A-1068-4804-89E7-0AFBAD5F885F}
 		{BEE70727-0C9E-42DE-A65B-5CB8F4EF1820} = {312E452A-1068-4804-89E7-0AFBAD5F885F}
 		{561B2DD7-455E-4464-B585-C8768C633EFC} = {71885AB0-0A46-4FC8-AEDF-F2DC4BEB0E67}
+		{917A4F64-8304-4228-B29A-E2FB474B761B} = {D0550510-0DCE-4B40-B4FB-091668E1C5FD}
 	EndGlobalSection
 EndGlobal
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -15,4 +15,5 @@
 * 2.2.1 - Remove (now unused) error handler parameter in literate (use ParseScript instead)
 * 2.2.2 - Nicer CSS style for API reference docs
 * 2.2.3 - Better recognition of links
-* 2.2.4 - Add inline Latex support (thanks to Xiang Zhang!)
+* 2.2.4 - Add inline Latex support (thanks to Xiang Zhang!)
+* 2.2.5 - Update templates, support multiple DLLs in metadata format
diff --git a/misc/templates/reference/module.cshtml b/misc/templates/reference/module.cshtml
@@ -5,20 +5,40 @@
 }
 
 @{
-  var nestModules = (IEnumerable<Module>)Model.Module.NestedModules;
-  var nestTypes = (IEnumerable<FSharp.MetadataFormat.Type>)Model.Module.NestedTypes;
-
+  // Get all the members & comment for the type
   var members = (IEnumerable<Member>)Model.Module.AllMembers;
   var comment = (Comment)Model.Module.Comment;
-  var byCategory =
-      members.GroupBy(m => m.Category).OrderBy(g => String.IsNullOrEmpty(g.Key) ? "ZZZ" : g.Key)
-             .Select((g, n) => new { Index = n, GroupKey = g.Key, Members = g.OrderBy(m => m.Name), Name = String.IsNullOrEmpty(g.Key) ? "Other module members" : g.Key});
+
+  // Group all members by their category which is an inline annotation
+  // that can be added to members using special XML comment:
+  //
+  //     /// [category:Something]
+  //
+  // ...and can be used to categorize members in large modules or types
+  // (but if this is not used, then all members end up in just one category)
+  var byCategory = members
+    .GroupBy(m => m.Category)
+    .OrderBy(g => String.IsNullOrEmpty(g.Key) ? "ZZZ" : g.Key)
+    .Select((g, n) => new { 
+      Index = n, 
+      GroupKey = g.Key, 
+      Members = g.OrderBy(m => m.Name), 
+      Name = String.IsNullOrEmpty(g.Key) ? "Other module members" : g.Key
+    });
+
+  // Get nested modules and nested types as statically typed collections
+  var nestModules = (IEnumerable<Module>)Model.Module.NestedModules;
+  var nestTypes = (IEnumerable<FSharp.MetadataFormat.Type>)Model.Module.NestedTypes;
 }
 
 <h1>@Model.Module.Name</h1>
 <div class="xmldoc">
   @foreach (var sec in comment.Sections) {
-    if (!byCategory.Any(g => g.GroupKey == sec.Key)) {
+    // XML comment for the type has multiple sections that can be labelled
+    // with categories (to give comment for an individual category). Here, 
+    // we print only those that belong to the <default> section.
+    if (!byCategory.Any(g => g.GroupKey == sec.Key))
+    {
       if (sec.Key != "<default>")        {
         <h2>@sec.Key</h2>
       }
@@ -28,6 +48,7 @@
 </div>
 @if (byCategory.Count() > 1)
 {
+  <!-- If there is more than 1 category in the type, generate TOC -->
   <h2>Table of contents</h2>
   <ul>
     @foreach (var g in byCategory)
@@ -37,59 +58,25 @@
   </ul>
 }
 
-<!-- TODO: Refactor me - copy & paste from 'namespaces.cshtml' -->
-
+<!-- Render nested types and modules, if there are any -->
 @if (nestTypes.Count() + nestModules.Count() > 0)
 {
   <h2>Nested types and modules</h2>
+  <div>
+    @RenderPart("part-nested", new {
+      Types = nestTypes,
+      Modules = nestModules
+    })
+  </div>
 }
 
-@if (nestTypes.Count() > 0)
-{
-  <table class="table table-bordered type-list">
-    <thead>
-      <tr><td>Type</td><td>Description</td></tr>
-    </thead>
-    <tbody>
-      @foreach (var it in nestTypes)
-      {
-        <tr>
-          <td class="type-name">
-            <a href="@(it.UrlName).html">@it.Name</a>
-          </td>
-          <td class="xmldoc">@it.Comment.Blurb</td>
-        </tr>
-      }
-    </tbody>
-  </table>
-}
-@if (nestModules.Count() > 0)
-{
-  <table class="table table-bordered module-list">
-    <thead>
-      <tr><td>Module</td><td>Description</td></tr>
-    </thead>
-    <tbody>
-      @foreach (var it in nestModules)
-      {
-        <tr>
-          <td class="module-name">
-            <a href="@(it.UrlName).html">@it.Name</a>
-          </td>
-          <td class="xmldoc">@it.Comment.Blurb</td>
-        </tr>
-      }
-    </tbody>
-  </table>
-}
-
-<!-- END TODO -->
-
-
-
 @foreach (var g in byCategory)
-{        
-  if (byCategory.Count() > 1) {
+{
+  // Iterate over all the categories and print members. If there are more than one
+  // categories, print the category heading (as <h2>) and add XML comment from the type
+  // that is related to this specific category.
+  if (byCategory.Count() > 1)
+  {
     <h2>@g.Name<a name="@("section" + g.Index.ToString())">&#160;</a></h2>    
     var info = comment.Sections.FirstOrDefault(kvp => kvp.Key == g.GroupKey);
     if (info.Key != null)
@@ -100,19 +87,19 @@
     }
   }
 
-  @RenderPart("members", new { 
+  @RenderPart("part-members", new { 
       Header = "Functions and values",
       TableHeader = "Function or value",
       Members = g.Members.Where(m => m.Kind == MemberKind.ValueOrFunction)
   })
 
-  @RenderPart("members", new { 
+  @RenderPart("part-members", new { 
       Header = "Type extensions",
       TableHeader = "Type extension",
       Members = g.Members.Where(m => m.Kind == MemberKind.TypeExtension)
   })
 
-  @RenderPart("members", new { 
+  @RenderPart("part-members", new { 
       Header = "Active patterns",
       TableHeader = "Active pattern",
       Members = g.Members.Where(m => m.Kind == MemberKind.ActivePattern)

diff --git a/misc/templates/reference/namespaces.cshtml b/misc/templates/reference/namespaces.cshtml
@@ -3,47 +3,15 @@
   Title = "Namespaces - " + Properties["project-name"];
 }
 
-<h1>@Model.Name.Name</h1>
+<h1>@Model.Name</h1>
 
 @foreach (var ns in Model.Namespaces)
 {
   <h2>@ns.Name</h2>
   <div>
-  @if (ns.Types.Length > 0) {
-    <table class="table table-bordered type-list">
-      <thead>
-        <tr><td>Type</td><td>Description</td></tr>
-      </thead>
-      <tbody>
-      @foreach (var it in ns.Types)
-	    {
-        <tr>
-		      <td class="type-name">
-            <a href="@(it.UrlName).html">@it.Name</a>
-		      </td>
-          <td class="xmldoc">@it.Comment.Blurb</td>
-        </tr>
-	    }
-      </tbody>
-    </table>
-  }
-  @if (ns.Modules.Length > 0) {
-    <table class="table table-bordered module-list">
-      <thead>
-        <tr><td>Module</td><td>Description</td></tr>
-      </thead>
-      <tbody>
-      @foreach (var it in ns.Modules)
-	    {
-        <tr>
-		      <td class="module-name">
-            <a href="@(it.UrlName).html">@it.Name</a>
-		      </td>
-          <td class="xmldoc">@it.Comment.Blurb</td>
-        </tr>
-	    }
-      </tbody>
-    </table>
-  }
+    @RenderPart("part-nested", new {
+      Types = ns.Types,
+      Modules = ns.Modules
+    })
   </div>
 }
diff --git a/misc/templates/reference/members.cshtml → misc/templates/reference/part-members.cshtml b/misc/templates/reference/members.cshtml → misc/templates/reference/part-members.cshtml
diff --git a/misc/templates/reference/part-nested.cshtml b/misc/templates/reference/part-nested.cshtml
@@ -0,0 +1,36 @@
+@if (Enumerable.Count(Model.Types) > 0) {
+  <table class="table table-bordered type-list">
+    <thead>
+      <tr><td>Type</td><td>Description</td></tr>
+    </thead>
+    <tbody>
+      @foreach (var it in Model.Types)
+      {
+        <tr>
+          <td class="type-name">
+            <a href="@(it.UrlName).html">@it.Name</a>
+          </td>
+          <td class="xmldoc">@it.Comment.Blurb</td>
+        </tr>
+      }
+    </tbody>
+  </table>
+}
+@if (Enumerable.Count(Model.Modules) > 0) {
+  <table class="table table-bordered module-list">
+    <thead>
+      <tr><td>Module</td><td>Description</td></tr>
+    </thead>
+    <tbody>
+      @foreach (var it in Model.Modules)
+      {
+        <tr>
+          <td class="module-name">
+            <a href="@(it.UrlName).html">@it.Name</a>
+          </td>
+          <td class="xmldoc">@it.Comment.Blurb</td>
+        </tr>
+      }
+    </tbody>
+  </table>
+}
diff --git a/misc/templates/reference/type.cshtml b/misc/templates/reference/type.cshtml
@@ -5,16 +5,34 @@
 }
 
 @{
+  // Get all the members & comment for the type
   var members = (IEnumerable<Member>)Model.Type.AllMembers;
   var comment = (Comment)Model.Type.Comment;
-  var byCategory =
-      members.GroupBy(m => m.Category).OrderBy(g => String.IsNullOrEmpty(g.Key) ? "ZZZ" : g.Key)
-             .Select((g, n) => new { Index = n, GroupKey = g.Key, Members = g.OrderBy(m => m.Name), Name = String.IsNullOrEmpty(g.Key) ? "Other type members" : g.Key });
+
+  // Group all members by their category which is an inline annotation
+  // that can be added to members using special XML comment:
+  //
+  //     /// [category:Something]
+  //
+  // ...and can be used to categorize members in large modules or types
+  // (but if this is not used, then all members end up in just one category)
+  var byCategory = members
+    .GroupBy(m => m.Category)
+    .OrderBy(g => String.IsNullOrEmpty(g.Key) ? "ZZZ" : g.Key)
+    .Select((g, n) => new { 
+      Index = n, 
+      GroupKey = g.Key, 
+      Members = g.OrderBy(m => m.Name), 
+      Name = String.IsNullOrEmpty(g.Key) ? "Other type members" : g.Key 
+    });
 }
 
 <h1>@Model.Type.Name</h1>
 <div class="xmldoc">
   @foreach (var sec in comment.Sections) {
+    // XML comment for the type has multiple sections that can be labelled
+    // with categories (to give comment for an individual category). Here, 
+    // we print only those that belong to the <default> section.
     if (!byCategory.Any(g => g.GroupKey == sec.Key)) {
       if (sec.Key != "<default>") {
         <h2>@sec.Key</h2>
@@ -25,6 +43,7 @@
 </div>
 @if (byCategory.Count() > 1)
 {
+  <!-- If there is more than 1 category in the type, generate TOC -->
   <h2>Table of contents</h2>
   <ul>
     @foreach (var g in byCategory)
@@ -34,6 +53,9 @@
   </ul>
 }
 @foreach (var g in byCategory) {
+  // Iterate over all the categories and print members. If there are more than one
+  // categories, print the category heading (as <h2>) and add XML comment from the type
+  // that is related to this specific category.
   if (byCategory.Count() > 1) {
     <h2>@g.Name<a name="@("section" + g.Index.ToString())">&#160;</a></h2>
     var info = comment.Sections.FirstOrDefault(kvp => kvp.Key == g.GroupKey);
@@ -44,31 +66,31 @@
     }
   }
 
-  @RenderPart("members", new {
+  @RenderPart("part-members", new {
     Header = "Union Cases",
     TableHeader = "Union Case",
-    Members = Model.Type.UnionCases
+    Members = g.Members.Where(m => m.Kind == MemberKind.UnionCase)
   })
 
-  @RenderPart("members", new {
+  @RenderPart("part-members", new {
     Header = "Record Fields",
     TableHeader = "Record Field",
-    Members = Model.Type.RecordFields
+    Members = g.Members.Where(m => m.Kind == MemberKind.RecordField)
   })
 
-  @RenderPart("members", new {
+  @RenderPart("part-members", new {
     Header = "Constructors",
     TableHeader = "Constructor",
     Members = g.Members.Where(m => m.Kind == MemberKind.Constructor)
   })
 
-  @RenderPart("members", new {
+  @RenderPart("part-members", new {
     Header = "Instance members",
     TableHeader = "Instance member",
     Members = g.Members.Where(m => m.Kind == MemberKind.InstanceMember)
   })
 
-  @RenderPart("members", new {
+  @RenderPart("part-members", new {
     Header = "Static members",
     TableHeader = "Static member",
     Members = g.Members.Where(m => m.Kind == MemberKind.StaticMember)