Reduce page count to avoid Node OOMs.

wixtoolset · Dec 13, 2022 · 08bad85 · 08bad85
1 parent 8cd8db4
commit 08bad85
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 105 deletions.
diff --git a/appveyor.yml b/appveyor.yml
@@ -10,7 +10,7 @@ configuration: Release
 
 environment:
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
-  NUGET_XMLDOC_MODE: skip
+  NUGET_XMLDOC_MODE: none
   GITHUB_ACCESS_TOKEN:
     secure: BuuXJ8z8dMoeeMPy4l7QbbNPFn1/CW9PRGZxMhH3IAFdtTftFKZHA7eqpBqiE2T3
 
@@ -26,6 +26,8 @@ build_script:
 artifacts:
   - path: build\deploy
     name: deploy-artifacts
+  - path: build\logs
+    name: log-artifacts
 
 deploy:
   - provider: WebDeploy

diff --git a/src/XmlDocToMarkdown/ConvertDocXmlToMarkdownCommand.cs b/src/XmlDocToMarkdown/ConvertDocXmlToMarkdownCommand.cs
@@ -38,7 +38,7 @@ public IEnumerable<Page> Convert()
         namespacesPageContent.AddRange(this.TypesByNamespace.Keys.OrderBy(n => n).Select(namespac => $"### [{namespac}]({PageId(namespac, "index.md")})"));
         pages.Add(new Page("index", namespacesPageContent));
 
-        // The rest: Pages for each namespace, types therein, and members thereof
+        // The rest: Pages for each namespace, types therein and members thereof
         foreach (var typesByNamespace in this.TypesByNamespace)
         {
             var namespaceName = typesByNamespace.Key;
@@ -55,41 +55,6 @@ public IEnumerable<Page> Convert()
         return pages;
     }
 
-    private static string PageId(string id)
-    {
-        return id.Replace("()", "_nop").Replace(", ", "_").Replace('(', '_').Replace(")", "").ToLowerInvariant();
-    }
-
-    private static string PageId(params string[] parts)
-    {
-        return PageId(String.Join(PageIdSeparator, parts));
-    }
-
-    private static string PageId(Member member)
-    {
-        var id = member switch
-        {
-            Constructor ctor => String.Join(PageIdSeparator, ctor.Namespace, ctor.TypeName, ctor.Signature),
-            Method method => String.Join(PageIdSeparator, method.Namespace, method.TypeName, method.Signature),
-            // todo: encode params?
-            Property property => String.Join(PageIdSeparator, property.Namespace, property.TypeName, property.Name),
-            Event evnt => String.Join(PageIdSeparator, evnt.Namespace, evnt.TypeName, evnt.Name),
-            _ => throw new ArgumentOutOfRangeException(),
-        };
-
-        return PageId(id);
-    }
-
-    private static string PageLink(DocType type)
-    {
-        return PageId(type.Name);
-    }
-
-    private static string PageLink(string id)
-    {
-        return PageId(id);
-    }
-
     private Page GenerateNamespacePage(string namespaceName, ICollection<DocType> types)
     {
         var content = new List<string>()
@@ -143,7 +108,8 @@ private IEnumerable<Page> GenerateTypePage(DocType type)
         {
             "---",
             "custom_edit_url: null",
-            $"sidebar_position: 1",
+            //"sidebar_position: 1",
+            "toc_max_heading_level: 2",
             "---",
             $"# {type.Name} {type.TypeFlavor}",
             type.Summary,
@@ -163,7 +129,7 @@ private IEnumerable<Page> GenerateTypePage(DocType type)
             var invoke = methods.Where(m => m.Name == "Invoke").SingleOrDefault();
             if (invoke is not null)
             {
-                content.AddRange(GenerateMethodDetails(invoke));
+                content.AddRange(GenerateMethodContent(invoke));
             }
         }
         else
@@ -187,30 +153,18 @@ private IEnumerable<Page> GenerateTypePage(DocType type)
         content.AddRange(SeeAlsoContent(type.SeeAlsos));
         content.Add($"`{type.AssemblyFileName}` version `{type.AssemblyVersion}`");
 
-        yield return new Page(PageId(type.Namespace, type.Name, "index"), content);
-
-        foreach (var constructor in constructors)
-        {
-            yield return new Page(PageId(constructor), GenerateMethodPage(constructor));
-        }
+        content.AddRange(constructors.SelectMany(constructor => GenerateMethodContent(constructor)));
 
         if (type.TypeFlavor != TypeFlavor.Delegate)
         {
-            foreach (var method in methods)
-            {
-                yield return new Page(PageId(method), GenerateMethodPage(method));
-            }
+            content.AddRange(methods.SelectMany(method => GenerateMethodContent(method)));
         }
 
-        foreach (var property in properties)
-        {
-            yield return new Page(PageId(property), GeneratePropertyPage(property));
-        }
+        content.AddRange(properties.SelectMany(property => GeneratePropertyContent(property)));
 
-        foreach (var eventDoc in events)
-        {
-            yield return new Page(PageId(eventDoc), GenerateEventPage(eventDoc));
-        }
+        content.AddRange(events.SelectMany(evnt => GenerateEventContent(evnt)));
+
+        yield return new Page(PageId(type.Namespace, type.Name), content);
 
 
         static IEnumerable<string> ListMembers(IEnumerable<Member> members, string memberTypeSingular, string memberTypePlural, bool addLinks = false)
@@ -226,19 +180,15 @@ static IEnumerable<string> ListMembers(IEnumerable<Member> members, string membe
 
                 foreach (var member in members)
                 {
-                    var name = member switch
-                    {
-                        Method method => method.Signature,
-                        _ => member.Name
-                    };
+                    var name = MemberSignature(member);
 
                     if (member is Field)
                     {
                         content.Add($"| {name} | {member.Summary} |");
                     }
                     else
                     {
-                        content.Add($"| [{name}]({PageLink(name)}) | {member.Summary} |");
+                        content.Add($"| [{name}]({MemberAnchor(name)}) | {member.Summary} |");
                     }
                 }
             }
@@ -247,31 +197,17 @@ static IEnumerable<string> ListMembers(IEnumerable<Member> members, string membe
         }
     }
 
-    private static IEnumerable<string> GenerateMethodPage(Method method)
+    private static IEnumerable<string> GenerateMethodContent(Method method)
     {
         var methodType = method is Constructor ? "Constructor" : "Method";
 
         var content = new List<string>()
         {
-            "---",
-            "custom_edit_url: null",
-            $"sidebar_position: 1",
-            "---",
-            $"# {method.Name}({GetParameterNamesForDisplay(method)}) {methodType}",
+            $"## {method.Name}({GetParameterNamesForDisplay(method)}) {methodType} {{{MemberAnchor(method)}}}",
             method.Summary,
+            "### Declaration",
         };
 
-        content.AddRange(GenerateMethodDetails(method));
-
-        return content;
-    }
-
-    private static IEnumerable<string> GenerateMethodDetails(Method method)
-    {
-        var content = new List<string>();
-
-        content.Add("## Declaration");
-
         var returnType = String.IsNullOrEmpty(method.ReturnType) ? String.Empty : $"{method.ReturnType.SimplifyTypeName(method.Namespace)} ";
 
         if (method.Parameters.IsNullOrEmpty())
@@ -292,7 +228,7 @@ private static IEnumerable<string> GenerateMethodDetails(Method method)
 
         if (!String.IsNullOrWhiteSpace(method.Returns))
         {
-            content.Add("## Return value");
+            content.Add("### Return value");
             content.Add(method is Constructor ? $"{method.Returns}" : $"`{method.ReturnType.SimplifyTypeName(method.Namespace)}` {method.Returns}");
         }
 
@@ -301,7 +237,7 @@ private static IEnumerable<string> GenerateMethodDetails(Method method)
 
         if (!method.Exceptions.IsNullOrEmpty())
         {
-            content.Add("## Exceptions");
+            content.Add("### Exceptions");
             content.Add("| Exception | Description |");
             content.Add("| --------- | ----------- |");
 
@@ -314,17 +250,13 @@ private static IEnumerable<string> GenerateMethodDetails(Method method)
         return content;
     }
 
-    private static IEnumerable<string> GeneratePropertyPage(Property property)
+    private static IEnumerable<string> GeneratePropertyContent(Property property)
     {
         var content = new List<string>()
         {
-            "---",
-            "custom_edit_url: null",
-            $"sidebar_position: 1",
-            "---",
-            $"# {property.Name} Property",
+            $"## {property.Name} Property {{{MemberAnchor(property)}}}",
             property.Summary,
-            "## Declaration",
+            "### Declaration",
         };
 
         var getter = property.CanRead ? "get;" : String.Empty;
@@ -351,7 +283,7 @@ private static IEnumerable<string> GeneratePropertyPage(Property property)
 
         if (!property.Exceptions.IsNullOrEmpty())
         {
-            content.Add("## Exceptions");
+            content.Add("### Exceptions");
             content.Add("| Exception | Description |");
             content.Add("| --------- | ----------- |");
 
@@ -364,21 +296,17 @@ private static IEnumerable<string> GeneratePropertyPage(Property property)
         return content;
     }
 
-    private static IEnumerable<string> GenerateEventPage(Event evnt)
+    private static IEnumerable<string> GenerateEventContent(Event evnt)
     {
         var content = new List<string>()
         {
-            "---",
-            "custom_edit_url: null",
-            $"sidebar_position: 1",
-            "---",
-            $"# {evnt.Name} Event",
+            $"## {evnt.Name} Event {{{MemberAnchor(evnt)}}}",
             evnt.Summary,
-            "## Declaration",
+            "### Declaration",
             "```cs",
             $"{evnt.Keywords} {evnt.Type.SimplifyTypeName(evnt.Namespace)} {evnt.Name}",
             "```",
-            "## Value",
+            "### Value",
             $"`{evnt.Type.SimplifyTypeName(evnt.Namespace)}`",
         };
 
@@ -397,7 +325,7 @@ private static IEnumerable<string> ParametersContent(IEnumerable<Parameter> para
     {
         var content = new List<string>()
         {
-            "## Parameters",
+            "### Parameters",
             "| Parameter | Type | Description |",
             "| --------- | ---- | ----------- |",
         };
@@ -416,7 +344,7 @@ private static IEnumerable<string> TextContent(string text, string title)
 
         if (!String.IsNullOrWhiteSpace(text))
         {
-            content.Add($"## {title}");
+            content.Add($"### {title}");
             content.Add(text);
         }
 
@@ -429,11 +357,45 @@ private static IEnumerable<string> SeeAlsoContent(IEnumerable<string> seeAlsos)
 
         if (!seeAlsos.IsNullOrEmpty())
         {
-            content.Add($"## See also");
+            content.Add($"### See also");
             // TODO: Make each entry a link.
             content.AddRange(seeAlsos.Select(s => $"- {s}"));
         }
 
         return content;
     }
+
+    private static string MemberSignature(Member member)
+    {
+        return member switch
+        {
+            Method method => method.Signature,
+            _ => member.Name
+        };
+    }
+
+    private static string MemberAnchor(Member member)
+    {
+        return MemberAnchor(MemberSignature(member));
+    }
+
+    private static string MemberAnchor(string id)
+    {
+        return $"#{SafeId(id)}";
+    }
+
+    private static string SafeId(string id)
+    {
+        return id.Replace("()", "_nop").Replace(", ", "_").Replace('(', '_').Replace(")", "").ToLowerInvariant();
+    }
+
+    private static string PageId(params string[] parts)
+    {
+        return SafeId(String.Join(PageIdSeparator, parts));
+    }
+
+    private static string PageLink(DocType type)
+    {
+        return SafeId(type.Name);
+    }
 }
diff --git a/src/XmlDocToMarkdown/DocXml.cs b/src/XmlDocToMarkdown/DocXml.cs
@@ -30,8 +30,6 @@ public static DocXml Parse(XDocument document, Assembly assembly)
     private Dictionary<string, FieldInfo> AssemblyFields { get; }
     private Dictionary<string, EventInfo> AssemblyEvents { get; }
 
-    //public string AssemblyName { get; }
-
     public string AssemblyFileName { get; }
 
     public string AssemblyVersion { get; }
@@ -44,7 +42,6 @@ private DocXml()
 
     private DocXml(XDocument document, Assembly assembly)
     {
-        //this.AssemblyName = assembly.FullName;
         this.AssemblyFileName = Path.GetFileName(assembly.Location);
         this.AssemblyVersion = FileVersionInfo.GetVersionInfo(assembly.Location).ProductVersion;
         this.Root = document.Root;

diff --git a/src/XmlDocToMarkdown/Program.cs b/src/XmlDocToMarkdown/Program.cs
@@ -23,6 +23,7 @@ public static int Main(string[] args)
         // TODO
         // - Create links
         //   - Handle `see` inline elements.
+        //   - Handle `seealso` elements.
         // - Handle generic types.
         // - Handle nested types.
         // - Handle out/ref parameters.

diff --git a/src/mkdoc/mkdoc.proj b/src/mkdoc/mkdoc.proj
@@ -37,6 +37,6 @@
     </ItemGroup>
 
     <Message Text="Generating API reference..." Importance="high" />
-    <Exec Command='$(OutDir)..\XmlDocToMarkdown.exe -title "WiX SDK reference" -out $(MSBuildProjectDir)..\Docusaurus\docs\reference\api @(XmlDocFile)' />
+    <Exec Command='$(OutDir)..\XmlDocToMarkdown.exe -title "WiX managed SDK" -out $(MSBuildProjectDir)..\Docusaurus\docs\reference\api @(XmlDocFile)' />
   </Target>
 </Project>