Skip to content

feat: basic API page output for .NET #9309

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

Merged
yufeih merged 7 commits into from
Oct 20, 2023
Merged

feat: basic API page output for .NET #9309

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
43cec1d
feat: basic api page output for .NET
yufeih Oct 19, 2023
f26910e
test(snapshot): update snapshots for c518ff189efc0f11dd9a6f0196f1070d…
yufeih Oct 19, 2023
1359ced
Merge branch 'main' into dotnet-apipage
yufeih Oct 19, 2023
1b7dad6
Api
yufeih Oct 19, 2023
217e8a1
Merge branch 'dotnet-apipage' of https://github.com/dotnet/docfx into…
yufeih Oct 19, 2023
425db7f
test(snapshot): update snapshots for 51159697f1977cae9bbebd97699bf9ed…
yufeih Oct 19, 2023
46723af
fix linux test failure on net6
yufeih Oct 20, 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
Api
  • Loading branch information
@yufeih
yufeih committed Oct 19, 2023
commit 1b7dad67a9fbd2883c28774336331c2f59b3a771
13 changes: 9 additions & 4 deletions src/Docfx.Build/ApiPage/ApiPageHtmlTemplate.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

#if NET7_0_OR_GREATER

using System.Net;
using static Docfx.Build.HtmlTemplate;

#nullable enable
Expand Down Expand Up @@ -41,12 +42,16 @@ public static HtmlTemplate Render(ApiPage page, Func<string, string> markup)

HtmlTemplate Api(Api api) => api.Value switch
{
Api1 api1 => Html($"<h1 class='section' data-uid id='{api1.id}'>{api1.api1}</h1>"),
Api2 api2 => Html($"<h2 class='section' data-uid id='{api2.id}'>{api2.api2}</h2>"),
Api3 api3 => Html($"<h3 class='section' data-uid id='{api3.id}'>{api3.api3}</h3>"),
Api4 api4 => Html($"<h4 class='section' data-uid id='{api4.id}'>{api4.api4}</h4>"),
Api1 api1 => Html($"<h1 class='section api' {Attributes(api1.metadata)} id='{api1.id}'>{api1.api1}</h1>"),
Api2 api2 => Html($"<h2 class='section api' {Attributes(api2.metadata)} id='{api2.id}'>{api2.api2}</h2>"),
Api3 api3 => Html($"<h3 class='section api' {Attributes(api3.metadata)} id='{api3.id}'>{api3.api3}</h3>"),
Api4 api4 => Html($"<h4 class='section api' {Attributes(api4.metadata)} id='{api4.id}'>{api4.api4}</h4>"),
};

HtmlTemplate Attributes(Dictionary<string, string>? metadata) => metadata is null
? default
: UnsafeHtml(string.Join(" ", metadata.Select(m => $"data-{WebUtility.HtmlEncode(m.Key)}='{WebUtility.HtmlEncode(m.Value)}'")));

HtmlTemplate Facts(Facts facts) => facts.facts.Length is 0 ? default : Html(
$"""
<div class="facts text-secondary">
Expand Down
8 changes: 4 additions & 4 deletions src/Docfx.Build/HtmlTemplate.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ struct HtmlTemplate

public static HtmlTemplate Html(FormattableString template)
{
var format = Regex.Replace(template.Format, "(\\s+[a-zA-Z0-9_-]+)=[\"']{(\\d)}[\"']", RenderAttribute);
var format = Regex.Replace(template.Format, "(\\s+[a-zA-Z0-9_-]+)=([\"']){(\\d)}[\"']", RenderAttribute);
var html = string.Format(format, Array.ConvertAll(template.GetArguments(), Render));
return new() { _html = html };

Expand All @@ -35,15 +35,15 @@ public static HtmlTemplate Html(FormattableString template)

string RenderAttribute(Match m)
{
var i = int.Parse(m.Groups[2].ToString());
var i = int.Parse(m.Groups[3].ToString());
var arg = template.GetArgument(i);

return arg switch
{
null => "",
bool b => b ? m.Groups[1].ToString() : "",
string str => !string.IsNullOrEmpty(str) ? $"{m.Groups[1]}=\"{WebUtility.HtmlEncode(str)}\"" : "",
_ => $"{m.Groups[1]}=\"{WebUtility.HtmlEncode(arg.ToString())}\"",
string str => !string.IsNullOrEmpty(str) ? $"{m.Groups[1]}={m.Groups[2]}{WebUtility.HtmlEncode(str)}{m.Groups[2]}" : "",
_ => $"{m.Groups[1]}={m.Groups[2]}{WebUtility.HtmlEncode(arg.ToString())}{m.Groups[2]}",
};
}
}
Expand Down
36 changes: 23 additions & 13 deletions src/Docfx.Dotnet/DotnetApiCatalog.Page.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,20 @@ void Heading(int level, string title, string? id = null)
});
}

void Api(int level, string title, ISymbol symbol)
{
var uid = VisitorHelper.GetId(symbol);
var id = Regex.Replace(uid, @"\W", "_");
var commentId = VisitorHelper.GetCommentId(symbol);
body.Add(level switch
{
1 => (Api)new Api1 { api1 = title, id = id, metadata = new() { ["uid"] = uid, ["commentId"] = commentId } },
2 => (Api)new Api2 { api2 = title, id = id, metadata = new() { ["uid"] = uid, ["commentId"] = commentId } },
3 => (Api)new Api3 { api3 = title, id = id, metadata = new() { ["uid"] = uid, ["commentId"] = commentId } },
4 => (Api)new Api4 { api4 = title, id = id, metadata = new() { ["uid"] = uid, ["commentId"] = commentId } },
});
}

void Namespace()
{
var namespaceSymbols = symbols.Select(n => n.symbol).ToHashSet(SymbolEqualityComparer.Default);
Expand All @@ -121,7 +135,7 @@ from s in allSymbols
where s.symbol.Kind is SymbolKind.NamedType && namespaceSymbols.Contains(s.symbol.ContainingNamespace)
select (symbol: (INamedTypeSymbol)s.symbol, s.compilation)).ToList();

Heading(1, title = $"Namespace {symbol}");
Api(1, title = $"Namespace {symbol}", symbol);

Summary(comment);
Namespaces();
Expand Down Expand Up @@ -159,7 +173,7 @@ void Types(Func<INamedTypeSymbol, bool> predicate, string headingText)

void Enum(INamedTypeSymbol type)
{
Heading(1, title = $"Enum {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)}");
Api(1, title = $"Enum {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)}", symbol);

body.Add(new Facts { facts = Facts().ToArray() });
Summary(comment);
Expand All @@ -176,7 +190,7 @@ void Enum(INamedTypeSymbol type)

void Delegate(INamedTypeSymbol type)
{
Heading(1, title = $"Delegate {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)}");
Api(1, title = $"Delegate {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)}", symbol);

body.Add(new Facts { facts = Facts().ToArray() });
Summary(comment);
Expand Down Expand Up @@ -204,7 +218,7 @@ void ClassLike(INamedTypeSymbol type)
_ => throw new InvalidOperationException(),
};

Heading(1, title = $"{typeHeader} {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)}");
Api(1, title = $"{typeHeader} {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp)}", symbol);

body.Add(new Facts { facts = Facts().ToArray() });
Summary(comment);
Expand Down Expand Up @@ -374,7 +388,7 @@ void InheritedMembers()

void MemberHeader(string headingText)
{
Heading(1, title = $"{headingText} {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp, overload: true)}");
Api(1, title = $"{headingText} {SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp, overload: true)}", symbol);
body.Add(new Facts { facts = Facts().ToArray() });
}

Expand Down Expand Up @@ -456,8 +470,7 @@ Parameter ToParameter(ITypeParameterSymbol param)

void Method(IMethodSymbol symbol, Compilation compilation, int headingLevel)
{
var fragment = Regex.Replace(VisitorHelper.GetId(symbol), @"\W", "_");
Heading(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), fragment);
Api(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), symbol);

var comment = Comment(symbol, compilation);
Summary(comment);
Expand All @@ -475,8 +488,7 @@ void Method(IMethodSymbol symbol, Compilation compilation, int headingLevel)

void Field(IFieldSymbol symbol, Compilation compilation, int headingLevel)
{
var fragment = Regex.Replace(VisitorHelper.GetId(symbol), @"\W", "_");
Heading(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), fragment);
Api(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), symbol);

var comment = Comment(symbol, compilation);
Summary(comment);
Expand All @@ -499,8 +511,7 @@ void Field(IFieldSymbol symbol, Compilation compilation, int headingLevel)

void Property(IPropertySymbol symbol, Compilation compilation, int headingLevel)
{
var fragment = Regex.Replace(VisitorHelper.GetId(symbol), @"\W", "_");
Heading(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), fragment);
Api(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), symbol);

var comment = Comment(symbol, compilation);
Summary(comment);
Expand All @@ -523,8 +534,7 @@ void Property(IPropertySymbol symbol, Compilation compilation, int headingLevel)

void Event(IEventSymbol symbol, Compilation compilation, int headingLevel)
{
var fragment = Regex.Replace(VisitorHelper.GetId(symbol), @"\W", "_");
Heading(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), fragment);
Api(headingLevel, SymbolFormatter.GetName(symbol, SyntaxLanguage.CSharp), symbol);

var comment = Comment(symbol, compilation);
Summary(comment);
Expand Down
3 changes: 2 additions & 1 deletion test/Docfx.Build.Tests/HtmlTemplateTest.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ public void HtmlTemplate_HtmlAttributesTest()
Assert.Equal("<h1></h1>", Html($"<h1 id=\"{false}\"></h1>").ToString());
Assert.Equal("<h1></h1>", Html($"<h1 id=\"{null}\"></h1>").ToString());
Assert.Equal("<h1></h1>", Html($"<h1 id='{""}'></h1>").ToString());
Assert.Equal("<h1 id=\"a\"></h1>", Html($"<h1 id='{"a"}'></h1>").ToString());
Assert.Equal("<h1 id='a'></h1>", Html($"<h1 id='{"a"}'></h1>").ToString());
Assert.Equal("<h1 id=\"a\"></h1>", Html($"<h1 id=\"{"a"}\"></h1>").ToString());
Assert.Equal("<h1 id></h1>", Html($"<h1 id=\"{true}\"></h1>").ToString());
}
}