feat: experimental support for markdown output (#9232)

* feat: initial support of markdown output * Fix tests * publish seed markdown to gh pages for preview * test(snapshot): update snapshots for 3b46445 * separate ns and assembly as two lines * test(snapshot): update snapshots for 2f52e6b * use soft break for info * test(snapshot): update snapshots for 7ebfed1 * basic TOC generation * test(snapshot): update snapshots for 5a64955 --------- Co-authored-by: Yufei Huang <yufeih@users.noreply.github.com>
dotnet · Sep 22, 2023 · f990af1 · f990af1
1 parent 98628ae
commit f990af1
Show file tree

Hide file tree

Showing 60 changed files with 3,039 additions and 27 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -45,6 +45,7 @@ jobs:
 
     - run: dotnet run -c Release --no-build -f net8.0 --project src/docfx -- metadata samples/seed/docfx.json
     - run: dotnet run -c Release --no-build -f net8.0 --project src/docfx -- build samples/seed/docfx.json --output docs/_site/seed
+    - run: dotnet run -c Release --no-build -f net8.0 --project src/docfx -- metadata samples/seed/docfx.json --outputFormat markdown --output docs/_site/seed/md
 
     - uses: actions/upload-artifact@v3
       if: matrix.os == 'ubuntu-latest'

diff --git a/samples/seed/dotnet/solution/CatLibrary/Class1.cs b/samples/seed/dotnet/solution/CatLibrary/Class1.cs
@@ -177,8 +177,8 @@ public void Jump(T ownType, K anotherOwnType, ref bool cheat)
         /// <summary>
         /// Addition operator of this class.
         /// </summary>
-        /// <param name="lsr">...</param>
-        /// <param name="rsr">~~~</param>
+        /// <param name="lsr">..</param>
+        /// <param name="rsr">~~</param>
         /// <returns>Result with <i>int</i> type.</returns>
         public static int operator +(Cat<T, K> lsr, int rsr) { return 1; }
 

diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.cs b/src/Docfx.Dotnet/DotnetApiCatalog.cs
@@ -119,6 +119,7 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config
             IncludePrivateMembers = configModel?.IncludePrivateMembers ?? false,
             GlobalNamespaceId = configModel?.GlobalNamespaceId,
             MSBuildProperties = configModel?.MSBuildProperties,
+            OutputFormat = configModel?.OutputFormat ?? default,
             OutputFolder = Path.GetFullPath(Path.Combine(outputDirectory, outputFolder)),
             CodeSourceBasePath = configModel?.CodeSourceBasePath,
             DisableDefaultFilter = configModel?.DisableDefaultFilter ?? false,

diff --git a/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs b/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs
@@ -11,6 +11,8 @@ internal class ExtractMetadataConfig
 
     public string OutputFolder { get; init; }
 
+    public MetadataOutputFormat OutputFormat { get; init; }
+
     public bool ShouldSkipMarkup { get; init; }
 
     public string FilterConfigFile { get; init; }

diff --git a/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs b/src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs
@@ -138,6 +138,12 @@ await LoadCompilationFromProject(project.AbsolutePath) is { } compilation)
             return;
         }
 
+        if (_config.OutputFormat is MetadataOutputFormat.Markdown)
+        {
+            MarkdownFormatter.Save(assemblies, _config, _options);
+            return;
+        }
+
         var projectMetadataList = new List<MetadataItem>();
         var extensionMethods = assemblies.SelectMany(assembly => assembly.Item1.FindExtensionMethods()).ToArray();
         var filter = new SymbolFilter(_config, _options);