docs: API generator could resolve obsolete parameter and render to AP…

…I table (#1493) * 📝 docs(api): Support for Obsolete attribute * 📝 docs: use no transition click example and api * 📝 docs: TOC i18n error
masastack · Aug 18, 2023 · fdff0e6 · fdff0e6
1 parent bb90b54
commit fdff0e6
Show file tree

Hide file tree

Showing 10 changed files with 42 additions and 32 deletions.
diff --git a/docs/Masa.Blazor.Docs/Components/Api/ApiDatatable.razor b/docs/Masa.Blazor.Docs/Components/Api/ApiDatatable.razor
@@ -5,14 +5,14 @@
 <AppSheet Class="mb-9">
     <MSimpleTable Class="api-table">
         <thead>
-            <tr>
-                @foreach (var header in Headers)
-                {
-                    <th style="@GetHeaderStyle(header)">
-                        <div class="subtitle">@I18n.T(header)</div>
-                    </th>
-                }
-            </tr>
+        <tr>
+            @foreach (var header in Headers)
+            {
+                <th style="@GetHeaderStyle(header)">
+                    <div class="subtitle">@I18n.T(header)</div>
+                </th>
+            }
+        </tr>
         </thead>
         <tbody>
         @foreach (var item in Items)
@@ -24,7 +24,9 @@
                         @if (header == "name")
                         {
                             <span class="subtitle">
-                                <MBadge Value="@(item.Required)" Color="transparent" Class="text-mono" OffsetY="10">
+                                <MBadge Value="@(item.Required)" Color="transparent"
+                                        Class="@(item.IsObsolete ? "text-mono text-decoration-line-through" : "text-mono")"
+                                        OffsetY="10">
                                     <BadgeContent>
                                         <MIcon Size="9" Color="red lighten-2">mdi-asterisk</MIcon>
                                     </BadgeContent>
@@ -125,7 +127,7 @@
             "name" => "width:144px",
             "type" => "width:264px;",
             _ => ""
-        };
+            };
     }
 
 }
diff --git a/docs/Masa.Blazor.Docs/Pages/Components.razor b/docs/Masa.Blazor.Docs/Pages/Components.razor
@@ -33,14 +33,8 @@
         }
         else
         {
-            <FadeTransition LeaveAbsolute>
-                <ShowTransitionElement Tag="div" Value="@IsApiTab">
-                    <Apis @bind-Value="@CurrentApi"
-                          Data="@_apiData"
-                          GithubUri="@ApiGithubUri">
-                    </Apis>
-                </ShowTransitionElement>
-                <ShowTransitionElement Tag="div" Value="@(!IsApiTab)">
+            <MTabsItems Value="IsApiTab.ToString()">
+                <MTabItem Value="@("False")" Transition="" Eager>
                     <DocumentMarkdownIt Source="@_md"
                                         OnTocParsed="@OnTocParsed"
                                         OnFrontMatterParsed="@OnFrontMatterParsed" />
@@ -49,8 +43,14 @@
                     {
                         <BackMatter Related="@_frontMatterMeta.Related"></BackMatter>
                     }
-                </ShowTransitionElement>
-            </FadeTransition>
+                </MTabItem>
+                <MTabItem Value="@("True")" Transition="">
+                    <Apis @bind-Value="@CurrentApi"
+                          Data="@_apiData"
+                          GithubUri="@ApiGithubUri">
+                    </Apis>
+                </MTabItem>
+            </MTabsItems>
         }
 
         <Contribute GithubUri="@(IsApiTab ? ApiGithubUri : ComponentGithubUri)" />

diff --git a/docs/Masa.Docs.Core/Components/OutlineCard.razor.css b/docs/Masa.Docs.Core/Components/OutlineCard.razor.css
@@ -1,7 +1,8 @@
 .m-outline-card {
-    position: relative;
-    padding: 16px;
     border-radius: 4px;
+    margin-top: 12px;
+    padding: 16px;
+    position: relative;
 }
 
 .m-outline-card__title {

diff --git a/docs/Masa.Docs.Shared/Shared/Toc.razor b/docs/Masa.Docs.Shared/Shared/Toc.razor
@@ -20,7 +20,7 @@
     <ChildContent>
         @if (_toc.Any())
         {
-            <div class="toc-content mb-2 ml-6">@I18n.T("Contents")</div>
+            <div class="toc-content mb-2 ml-6">@I18n.T("Toc")</div>
         }
         <ul class="mb-6">
             @foreach (var item in _toc)

diff --git a/docs/Masa.Docs.Shared/wwwroot/css/docs.css b/docs/Masa.Docs.Shared/wwwroot/css/docs.css
@@ -331,7 +331,6 @@ a.text-dec-none {
     }
 
     .overview .project-content__title {
-        margin-bottom: 8px;
         font-weight: 700;
         line-height: 24px;
     }

diff --git a/docs/Masa.Docs.Shared/wwwroot/locale/en-US.json b/docs/Masa.Docs.Shared/wwwroot/locale/en-US.json
@@ -116,7 +116,7 @@
   "InvertExampleColors": "Invert example colors",
   "ViewOnGithub": "View on github",
   "ViewSource": "View source",
-  "Contents": "Contents",
+  "Toc": "Contents",
   "SeniorSponsor": "Senior sponsor",
   "ComponentPages": "Component Pages",
   "NextPage": "Next Page",

diff --git a/docs/Masa.Docs.Shared/wwwroot/locale/zh-CN.json b/docs/Masa.Docs.Shared/wwwroot/locale/zh-CN.json
@@ -116,7 +116,7 @@
   "InvertExampleColors": "反转示例颜色",
   "ViewOnGithub": "在 Github 上查看",
   "ViewSource": "查看源代码",
-  "Contents": "目录",
+  "Toc": "目录",
   "SeniorSponsor": "高级赞助商",
   "Sponsor": "赞助商",
   "Required": "必填",

diff --git a/src/Masa.Blazor.Docs.ApiGenerator/ApiGenerator.cs b/src/Masa.Blazor.Docs.ApiGenerator/ApiGenerator.cs
@@ -88,6 +88,8 @@ public class ParameterInfo
         public string? Description {{ get; set; }}
 
         public bool Required {{ get; set; }}
+
+        public bool IsObsolete {{ get; set; }}
     }}
 }}");
 
@@ -202,7 +204,9 @@ private static void AnalyzeParameters(INamedTypeSymbol classSymbol, List<Paramet
                         }
                     }
 
-                    var parameterInfo = new ParameterInfo(parameterSymbol.Name, typeText, typeDesc, defaultValue);
+                    var isObsolete = attrs.FirstOrDefault(attr => attr.AttributeClass?.Name == "ObsoleteAttribute") is not null;
+
+                    var parameterInfo = new ParameterInfo(parameterSymbol.Name, typeText, typeDesc, defaultValue, isObsolete);
 
                     if (type.Name.StartsWith("RenderFragment"))
                     {

diff --git a/src/Masa.Blazor.Docs.ApiGenerator/GenComponentMeta.cs b/src/Masa.Blazor.Docs.ApiGenerator/GenComponentMeta.cs
@@ -32,7 +32,8 @@ public static partial class ApiGenerator
                 Type = ""{item.Type}"",
                 TypeDesc = @""{item.TypeDesc}"",
                 DefaultValue = ""{item.DefaultValue}"",
-                Required = {item.Required.ToString().ToLower()}
+                Required = {item.Required.ToString().ToLower()},
+                IsObsolete = {item.IsObsolete.ToString().ToLower()},
             }});");
             }
 

diff --git a/src/Masa.Blazor.Docs.ApiGenerator/ParameterInfo.cs b/src/Masa.Blazor.Docs.ApiGenerator/ParameterInfo.cs
@@ -2,23 +2,26 @@
 
 internal class ParameterInfo
 {
-    public ParameterInfo(string name, string type, string? typeDesc = null, string? defaultValue = null)
+    public ParameterInfo(string name, string type, string? typeDesc = null, string? defaultValue = null, bool isObsolete = false)
     {
         Name = name;
         Type = type;
         TypeDesc = typeDesc;
         DefaultValue = defaultValue;
+        IsObsolete = isObsolete;
     }
-    
+
     public string Name { get; set; } = null!;
 
     public string Type { get; set; } = null!;
-    
+
     public string? TypeDesc { get; set; }
 
     public string? DefaultValue { get; set; }
 
     public string? Description { get; set; }
 
     public bool Required { get; set; }
-}
+
+    public bool IsObsolete { get; set; }
+}