public override async Task Generate(DirectoryInfo directory, ProgrammableBlockApi api)
{
var fileName = Path.Combine(directory.FullName, "Namespace-Index.md");
using (var file = File.CreateText(fileName))
{
var writer = new MarkdownWriter(file);
await writer.BeginParagraphAsync();
await writer.WriteAsync($"← {MarkdownInline.HRef("Index", "Api-Index")}");
await writer.EndParagraphAsync();
await writer.WriteHeaderAsync(3, "Assemblies");
await writer.BeginParagraphAsync();
await writer.WriteLineAsync("These are the game assemblies used by programmable block scripts.");
await writer.WriteLineAsync();
foreach (var assembly in api.Entries.Select(e => e.AssemblyName).Distinct().OrderBy(n => n))
await writer.WriteLineAsync($"{assembly}.dll ");
await writer.EndParagraphAsync();
await writer.WriteHeaderAsync(3, "Types");
await writer.BeginParagraphAsync();
await writer.WriteAsync("This index contains all types and members available to ingame scripting - with exception to the .NET types, because including those would have made the listing far too big. There will be links to Microsoft's own documentation for those types where appropriate.");
await writer.EndParagraphAsync();
foreach (var blockGroup in api.Entries.Where(e => e.Member is Type).GroupBy(e => e.Member.GetNamespace()).OrderBy(g => g.Key))
{
await writer.WriteHeaderAsync(3, blockGroup.Key);
await writer.BeginParagraphAsync();
foreach (var type in blockGroup.OrderBy(e => e.ToString(ApiEntryStringFlags.ShortDisplayName | ApiEntryStringFlags.DeclaringTypes)))
await writer.WriteLineAsync(MemberGenerator.LinkTo(WebUtility.HtmlEncode(type.ToString(ApiEntryStringFlags.ShortDisplayName | ApiEntryStringFlags.DeclaringTypes)), type));
await writer.EndParagraphAsync();
}
await writer.FlushAsync();
}
}
async Task GenerateNamespaceDoc(DirectoryInfo directory, IGrouping <string, ApiEntry> ns)
{
var fileName = Path.Combine(directory.FullName, ToMdFileName(ns.Key));
using (var file = File.CreateText(fileName))
{
var writer = new MarkdownWriter(file);
await writer.BeginParagraphAsync();
await writer.WriteAsync($"← {MarkdownInline.HRef("Index", "Api-Index")} ← {MarkdownInline.HRef("Namespace Index", "Namespace-Index")}");
await writer.EndParagraphAsync();
await writer.WriteHeaderAsync(1, ns.Key);
await writer.BeginParagraphAsync();
foreach (var typeGroup in ns.GroupBy(e => e.DeclaringEntry ?? e).OrderBy(g => g.Key.FullName))
{
await writer.WriteLineAsync(MarkdownInline.Strong(MemberGenerator.LinkTo(typeGroup.Key.Name, typeGroup.Key)));
}
await writer.EndParagraphAsync();
await writer.FlushAsync();
}
}
IEnumerable <string> AncestorsOf(ApiEntry entry)
{
entry = entry.BaseEntry;
while (entry != null)
{
yield return(MemberGenerator.LinkTo(entry.ToString(ApiEntryStringFlags.None), entry));
entry = entry.BaseEntry;
}
}
async Task WriteTable(string title, IEnumerable <ApiEntry> entries, ProgrammableBlockApi api, ApiEntry entry, MarkdownWriter writer)
{
var items = entries.ToList();
if (items.Count == 0)
{
return;
}
await writer.WriteHeaderAsync(4, title);
await writer.BeginTableAsync("Member", "Description");
foreach (var item in items)
{
await writer.BeginTableCellAsync();
await writer.WriteAsync(MemberGenerator.LinkTo(item.ToString(ApiEntryStringFlags.ParameterTypes), item));
await writer.EndTableCellAsync();
await writer.BeginTableCellAsync();
var obsoleteAttribute = item.Member.GetCustomAttribute <ObsoleteAttribute>(false);
if (obsoleteAttribute != null)
{
await writer.BeginParagraphAsync();
if (string.IsNullOrWhiteSpace(obsoleteAttribute.Message))
{
await writer.WriteAsync(MarkdownInline.Emphasized(MarkdownInline.Strong("Obsolete")));
}
else
{
await writer.WriteAsync(MarkdownInline.Emphasized($"{MarkdownInline.Strong("Obsolete:")} {obsoleteAttribute.Message}"));
}
await writer.EndParagraphAsync();
}
var context = new XmlDocWriteContext(key => ResolveTypeReference(api, key));
item.Documentation?.Summary?.WriteMarkdown(context, writer);
if (entry != item.DeclaringEntry)
{
await writer.BeginParagraphAsync();
await writer.WriteAsync(MarkdownInline.Emphasized($"Inherited from {MemberGenerator.LinkTo(item.DeclaringEntry.ToString(ApiEntryStringFlags.ShortDisplayName), item.DeclaringEntry)}"));
await writer.EndParagraphAsync();
}
await writer.EndTableCellAsync();
}
await writer.EndTableAsync();
}
async Task WriteInheritors(ApiEntry entry, MarkdownWriter writer)
{
await writer.BeginParagraphAsync();
await writer.WriteLineAsync(MarkdownInline.Strong("Inheritors: "));
foreach (var iface in entry.InheritorEntries)
{
await writer.WriteUnorderedListItemAsync(MemberGenerator.LinkTo(iface.ToString(ApiEntryStringFlags.ShortDisplayName), iface));
}
await writer.EndParagraphAsync();
}
async Task WriteInheritors(ApiEntry entry, MarkdownWriter writer)
{
await writer.BeginParagraphAsync();
await writer.WriteLineAsync(MarkdownInline.Strong("Inheritors: "));
var lines = entry.InheritorEntries.Select(iface => new
{
Text = iface.ToString(ApiEntryStringFlags.ShortDisplayName),
Interface = iface
})
.OrderBy(o => o.Text)
.Select(o => MemberGenerator.LinkTo(o.Text, o.Interface))
.ToList();
foreach (var line in lines)
{
await writer.WriteUnorderedListItemAsync(line);
}
await writer.EndParagraphAsync();
}