Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: experimental support for markdown output #9232

Merged
merged 14 commits into from
Sep 22, 2023
Merged

feat: experimental support for markdown output #9232

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
959506d
feat: initial support of markdown output
yufeih Sep 21, 2023
e491edf
Fix tests
yufeih Sep 21, 2023
6b0f6f1
publish seed markdown to gh pages for preview
yufeih Sep 21, 2023
b2bf6b0
test(snapshot): update snapshots for 3b46445534ea21756d022145d661c592…
yufeih Sep 21, 2023
51dbd80
separate ns and assembly as two lines
yufeih Sep 21, 2023
ff6b3c3
Merge branch 'md' of https://github.com/dotnet/docfx into md
yufeih Sep 21, 2023
a4bd9eb
test(snapshot): update snapshots for 2f52e6b0101fb123e873d2672989ebf3…
yufeih Sep 21, 2023
a7cbf86
use soft break for info
yufeih Sep 21, 2023
92c3afc
Merge branch 'md' of https://github.com/dotnet/docfx into md
yufeih Sep 21, 2023
78c1554
test(snapshot): update snapshots for 7ebfed10487aef28cf049e4736659ec0…
yufeih Sep 21, 2023
82c9d25
basic TOC generation
yufeih Sep 21, 2023
3f96305
Merge branch 'md' of https://github.com/dotnet/docfx into md
yufeih Sep 21, 2023
ffe7a17
Merge branch 'main' into md
yufeih Sep 21, 2023
9ffdc84
test(snapshot): update snapshots for 5a649558a6d877a69d2ad0ee23907e52…
yufeih Sep 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
basic TOC generation
  • Loading branch information
@yufeih
yufeih committed Sep 21, 2023
commit 82c9d254f4e3f7e4878119ac167528292a0f4fdd
35 changes: 33 additions & 2 deletions src/Docfx.Dotnet/MarkdownFormatter.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

using System.Text;
using Docfx.Common;
using Docfx.DataContracts.Common;
using Docfx.DataContracts.ManagedReference;
using Docfx.Plugins;
using Microsoft.CodeAnalysis;
Expand All @@ -20,6 +21,8 @@ public static void Save(List<(IAssemblySymbol, Compilation)> assemblies, Extract

Directory.CreateDirectory(config.OutputFolder);

var toc = new TocViewModel();
var tocNodeByNamespace = new Dictionary<string, TocItemViewModel>();
var filter = new SymbolFilter(config, options);
var extensionMethods = assemblies.SelectMany(assembly => assembly.Item1.FindExtensionMethods()).Where(filter.IncludeApi).ToArray();
var allAssemblies = new HashSet<IAssemblySymbol>(assemblies.Select(a => a.Item1), SymbolEqualityComparer.Default);
Expand All @@ -30,9 +33,13 @@ public static void Save(List<(IAssemblySymbol, Compilation)> assemblies, Extract
SaveCore(assembly, compilation);
}

SortTocItems(toc);
YamlUtility.Serialize(Path.Combine(config.OutputFolder, "toc.yml"), toc, YamlMime.TableOfContent);

void SaveCore(IAssemblySymbol assembly, Compilation compilation)
{
Logger.LogInfo($"Processing {assembly.Name}");

VisitNamespace(assembly.GlobalNamespace);

void VisitNamespace(INamespaceSymbol symbol)
Expand All @@ -52,8 +59,20 @@ void VisitNamedType(INamedTypeSymbol symbol)
if (!filter.IncludeApi(symbol))
return;

foreach (var subtype in symbol.GetTypeMembers())
VisitNamedType(subtype);
var ns = symbol.ContainingNamespace.ToString()!;
if (!tocNodeByNamespace.TryGetValue(ns, out var tocNode))
{
tocNode = new() { Name = ns, Href = $"{VisitorHelper.GetId(symbol.ContainingNamespace)}.md" };
tocNodeByNamespace.Add(ns, tocNode);
toc.Add(tocNode);
}

foreach (var type in symbol.GetTypeMembers())
{
tocNode.Items ??= new();
tocNode.Items.Add(new() { Name = type.Name, Href = $"{VisitorHelper.GetId(symbol)}.md" });
VisitNamedType(type);
}

Save(symbol);
}
Expand All @@ -68,6 +87,7 @@ void Save(INamedTypeSymbol symbol)
case TypeKind.Enum: Enum(); break;
case TypeKind.Delegate: Delegate(); break;
case TypeKind.Interface or TypeKind.Structure or TypeKind.Class: Class(); break;
default: throw new NotSupportedException($"Unknown symbol type kind {symbol.TypeKind}");
}

var filename = Path.Combine(config.OutputFolder, VisitorHelper.GetId(symbol) + ".md");
Expand Down Expand Up @@ -516,6 +536,17 @@ string Cref(string commentId)
}
}

static void SortTocItems(TocViewModel node)
{
node.Sort((a, b) => a.Name.CompareTo(b.Name));

foreach (var child in node)
{
if (child.Items is not null)
SortTocItems(child.Items);
}
}

static string Escape(string text)
{
return text;
Expand Down
8 changes: 8 additions & 0 deletions src/docfx/Properties/launchSettings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,14 @@
"environmentVariables": {
}
},
// Run `docfx metadata --outputFormat markdown` command.
"docfx metadata --markdown": {
"commandName": "Project",
"commandLineArgs": "metadata ../../samples/seed/docfx.json --outputFormat markdown",
"workingDirectory": ".",
"environmentVariables": {
}
},
// Run `docfx serve` command and launch browser.
"docfx serve": {
"commandName": "Project",
Expand Down