feat: toggle log severity using rules config (#9460)

* feat: toggle log severity using rules config * Update docfx-json-reference.md * add more warning codes in metadata command --------- Co-authored-by: Yufei Huang <[email protected]>
dotnet · Nov 24, 2023 · d68b9d2 · d68b9d2
1 parent 2ba0c48
commit d68b9d2
Show file tree

Hide file tree

Showing 12 changed files with 42 additions and 14 deletions.
diff --git a/docs/reference/docfx-json-reference.md b/docs/reference/docfx-json-reference.md
@@ -10,6 +10,20 @@ The `docfx.json` file indicates that the directory is the root of a docfx projec
 }
 ```
 
+## Global properties 
+
+### `rules`
+
+Overrides default log message severity level. Key is the log code, supported values are `verbose`, `info`, `suggestion`, `warning`, `error`:
+
+```json
+{
+  "rules": {
+    "InvalidHref": "info"
+  }
+}
+```
+
 ## `build`
 
 Configuration options that are applied for `docfx build` command:

diff --git a/samples/seed/docfx.json b/samples/seed/docfx.json
@@ -92,5 +92,8 @@
         "TODO": "alert alert-secondary"
       }
     }
+  },
+  "rules": {
+    "InvalidCref": "info"
   }
 }
diff --git a/src/Docfx.App/Config/DocfxConfig.cs b/src/Docfx.App/Config/DocfxConfig.cs
@@ -3,6 +3,8 @@
 
 #nullable enable
 
+using Docfx.Common;
+
 namespace Docfx;
 
 class DocfxConfig
@@ -14,4 +16,6 @@ class DocfxConfig
     public BuildJsonConfig? build { get; init; }
 
     public PdfJsonConfig? pdf { get; init; }
+
+    public Dictionary<string, LogLevel>? rules { get; init; }
 }
diff --git a/src/Docfx.App/Docset.cs b/src/Docfx.App/Docset.cs
@@ -71,7 +71,11 @@ internal static (DocfxConfig, string configDirectory) GetConfig(string configFil
         if (!File.Exists(configFile))
             throw new FileNotFoundException($"Cannot find config file {configFile}");
 
-        return (JsonUtility.Deserialize<DocfxConfig>(configFile), Path.GetDirectoryName(configFile));
+        var config = JsonUtility.Deserialize<DocfxConfig>(configFile);
+
+        Logger.Rules = config.rules;
+
+        return (config, Path.GetDirectoryName(configFile));
     }
 
 

diff --git a/src/Docfx.Common/Loggers/ConsoleLogListener.cs b/src/Docfx.Common/Loggers/ConsoleLogListener.cs
@@ -48,6 +48,8 @@ public void WriteLine(ILogItem item)
         {
             if (level >= LogLevel.Warning)
                 message.Append($"{level.ToString().ToLowerInvariant()}: ");
+            if (!string.IsNullOrEmpty(item.Code))
+                message.Append($"{item.Code}: ");
         }
 
         message.Append(item.Message);

diff --git a/src/Docfx.Common/Loggers/Logger.cs b/src/Docfx.Common/Loggers/Logger.cs
@@ -18,6 +18,7 @@ public static class Logger
     private static int _errorCount = 0;
     public static volatile LogLevel LogLevelThreshold = LogLevel.Info;
     public static volatile bool WarningsAsErrors = false;
+    public static volatile Dictionary<string, LogLevel> Rules;
 
     public static void RegisterListener(ILoggerListener listener)
     {
@@ -45,8 +46,13 @@ public static void UnregisterAllListeners()
         _syncListener.RemoveAllListeners();
     }
 
-    public static void Log(ILogItem item)
+    private static void Log(LogItem item)
     {
+        if (Rules is not null && !string.IsNullOrEmpty(item.Code) && Rules.TryGetValue(item.Code, out var level))
+        {
+            item.LogLevel = level;
+        }
+
         if (item.LogLevel < LogLevelThreshold)
         {
             return;

diff --git a/src/Docfx.Dotnet/CompilationHelper.cs b/src/Docfx.Dotnet/CompilationHelper.cs
@@ -155,7 +155,7 @@ void GetReferenceAssembliesCore(PEFile assembly)
                 var file = assemblyResolver.FindAssemblyFile(reference);
                 if (file is null)
                 {
-                    Logger.LogWarning($"Unable to resolve assembly reference {reference}");
+                    Logger.LogWarning($"Unable to resolve assembly reference {reference}", code: "InvalidAssemblyReference");
                     continue;
                 }
 

diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.Toc.cs b/src/Docfx.Dotnet/DotnetApiCatalog.Toc.cs
@@ -42,8 +42,6 @@ class TocNode
 
     private static List<TocNode> CreateToc(List<(IAssemblySymbol symbol, Compilation compilation)> assemblies, ExtractMetadataConfig config, DotnetApiOptions options)
     {
-        Logger.LogWarning($"Markdown output format is experimental.");
-
         Directory.CreateDirectory(config.OutputFolder);
 
         var filter = new SymbolFilter(config, options);

diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.cs b/src/Docfx.Dotnet/DotnetApiCatalog.cs
@@ -40,10 +40,12 @@ public static async Task GenerateManagedReferenceYamlFiles(string configPath, Do
         try
         {
             var configDirectory = Path.GetDirectoryName(Path.GetFullPath(configPath));
-
             var config = JObject.Parse(File.ReadAllText(configPath));
             if (config.TryGetValue("metadata", out var value))
+            {
+                Logger.Rules = config["rules"]?.ToObject<Dictionary<string, LogLevel>>();
                 await Exec(value.ToObject<MetadataJsonConfig>(JsonUtility.DefaultSerializer.Value), options, configDirectory);
+            }
         }
         finally
         {

diff --git a/src/Docfx.Dotnet/ManagedReference/Visitors/SymbolVisitorAdapter.cs b/src/Docfx.Dotnet/ManagedReference/Visitors/SymbolVisitorAdapter.cs
@@ -727,7 +727,7 @@ string ResolveCode(string source)
             var path = Path.GetFullPath(Path.Combine(basePath, source));
             if (!File.Exists(path))
             {
-                Logger.LogWarning($"Source file '{path}' not found.");
+                Logger.LogWarning($"Source file '{path}' not found.", code: "CodeNotFound");
                 return null;
             }
 

diff --git a/src/Docfx.Dotnet/Parsers/XmlComment.cs b/src/Docfx.Dotnet/Parsers/XmlComment.cs
@@ -106,7 +106,7 @@ public static XmlComment Parse(string xml, XmlCommentParserContext context = nul
         // Quick turnaround for badly formed XML comment
         if (xml.StartsWith("<!-- Badly formed XML comment ignored for member ", StringComparison.Ordinal))
         {
-            Logger.LogWarning($"Invalid triple slash comment is ignored: {xml}");
+            Logger.LogWarning($"Invalid XML comment: {xml}", code: "InvalidXmlComment");
             return null;
         }
         try
@@ -360,7 +360,7 @@ private void ResolveCrefLink(XNode node, string nodeSelector, Action<string, str
                     }
                 }
 
-                Logger.Log(LogLevel.Warning, $"Invalid cref value \"{cref}\" found in XML documentation comment {detailedInfo}.");
+                Logger.Log(LogLevel.Warning, $"Invalid cref value \"{cref}\" found in XML documentation comment {detailedInfo}.", code: "InvalidCref");
 
                 if (cref.StartsWith("!:"))
                 {

diff --git a/src/Docfx.MarkdigEngine.Extensions/Constants.cs b/src/Docfx.MarkdigEngine.Extensions/Constants.cs
@@ -6,9 +6,4 @@ namespace Docfx.MarkdigEngine.Extensions;
 internal static class Constants
 {
     public static readonly string FencedCodePrefix = "lang-";
-
-    public static class WarningCodes
-    {
-        public const string InvalidTabGroup = "InvalidTabGroup";
-    }
 }