diff --git a/appveyor.yml b/appveyor.yml index eeec3e5e..116411d7 100644 --- 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 index ce8673a0..6934c9d3 100644 --- a/src/XmlDocToMarkdown/ConvertDocXmlToMarkdownCommand.cs +++ b/src/XmlDocToMarkdown/ConvertDocXmlToMarkdownCommand.cs @@ -38,7 +38,7 @@ public IEnumerable 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 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 types) { var content = new List() @@ -143,7 +108,8 @@ private IEnumerable 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 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 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 ListMembers(IEnumerable members, string memberTypeSingular, string memberTypePlural, bool addLinks = false) @@ -226,11 +180,7 @@ static IEnumerable ListMembers(IEnumerable 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) { @@ -238,7 +188,7 @@ static IEnumerable ListMembers(IEnumerable members, string membe } else { - content.Add($"| [{name}]({PageLink(name)}) | {member.Summary} |"); + content.Add($"| [{name}]({MemberAnchor(name)}) | {member.Summary} |"); } } } @@ -247,31 +197,17 @@ static IEnumerable ListMembers(IEnumerable members, string membe } } - private static IEnumerable GenerateMethodPage(Method method) + private static IEnumerable GenerateMethodContent(Method method) { var methodType = method is Constructor ? "Constructor" : "Method"; var content = new List() { - "---", - "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 GenerateMethodDetails(Method method) - { - var content = new List(); - - 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 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 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 GenerateMethodDetails(Method method) return content; } - private static IEnumerable GeneratePropertyPage(Property property) + private static IEnumerable GeneratePropertyContent(Property property) { var content = new List() { - "---", - "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 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 GeneratePropertyPage(Property property) return content; } - private static IEnumerable GenerateEventPage(Event evnt) + private static IEnumerable GenerateEventContent(Event evnt) { var content = new List() { - "---", - "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 ParametersContent(IEnumerable para { var content = new List() { - "## Parameters", + "### Parameters", "| Parameter | Type | Description |", "| --------- | ---- | ----------- |", }; @@ -416,7 +344,7 @@ private static IEnumerable 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 SeeAlsoContent(IEnumerable 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 index 43e85b02..389d073f 100644 --- a/src/XmlDocToMarkdown/DocXml.cs +++ b/src/XmlDocToMarkdown/DocXml.cs @@ -30,8 +30,6 @@ public static DocXml Parse(XDocument document, Assembly assembly) private Dictionary AssemblyFields { get; } private Dictionary 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 index 6ac0f032..6c815da0 100644 --- 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 index c0822718..1952518c 100644 --- a/src/mkdoc/mkdoc.proj +++ b/src/mkdoc/mkdoc.proj @@ -37,6 +37,6 @@ - + \ No newline at end of file