feat: add overridable metadata output json config

docs/reference/docfx-json-reference.md

@@ -295,9 +295,13 @@ Configuration options that are applied for `docfx metadata` command:
 
 Specifies the source projects using [File Mappings](#file-mappings).
 
+### `output`
+
+Defines the output folder of the generated metadata files relative to `docfx.json` directory. The `docfx metadata --output <outdir>` command line argument overrides this value.
+
 ### `dest`
 
-Defines the output folder of the generated metadata files. Relative paths are relative to the docfx.json file being used. To go up a folder use `../`.
+Defines the output folder of the generated metadata files relative to `docfx.json` directory.  The `docfx metadata --output <outdir>` command line argument prepends this value.
 
 ### `shouldSkipMarkup`
 

samples/Directory.Build.props

@@ -1,5 +1,10 @@
 <Project>
   <PropertyGroup>
     <IsPackable>false</IsPackable>
+    <!--
+      Suppress warnings similar to the following:
+          warning NU1507: There are 2 package sources defined in your configuration.
+     -->
+    <NoWarn>$(NoWarn);NU1507</NoWarn>
   </PropertyGroup>
 </Project>

samples/seed/docfx.json

@@ -18,7 +18,7 @@
       ],
       "namespaceLayout": "nested",
       "enumSortOrder": "declaringOrder",
-      "dest": "obj/api"
+      "output": "obj/api"
     }
   ],
   "build": {

src/Docfx.App/Config/BuildJsonConfig.cs

@@ -41,13 +41,15 @@ internal class BuildJsonConfig
 
     /// <summary>
     /// Defines the output folder of the generated build files.
+    /// Command line --output argument prepends this value.
     /// </summary>
     [Obsolete("Use output instead.")]
     [JsonProperty("dest")]
     public string Destination { get; set; }
 
     /// <summary>
     /// Defines the output folder of the generated build files.
+    /// Command line --output argument override this value.
     /// </summary>
     [JsonProperty("output")]
     public string Output { get; set; }

src/Docfx.Dotnet/DotnetApiCatalog.cs

@@ -68,7 +68,7 @@ internal static async Task Exec(MetadataJsonConfig config, DotnetApiOptions opti
                     EnvironmentContext.SetGitFeaturesDisabled(item.DisableGitFeatures);
 
                     // TODO: Use plugin to generate metadata for files with different extension?
-                    using var worker = new ExtractMetadataWorker(ConvertConfig(item, outputDirectory ?? configDirectory), options);
+                    using var worker = new ExtractMetadataWorker(ConvertConfig(item, configDirectory, outputDirectory), options);
                     await worker.ExtractMetadataAsync();
                 }
 
@@ -103,11 +103,14 @@ private static void EnsureMSBuildLocator()
         }
     }
 
-    private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig configModel, string outputDirectory)
+    private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig configModel, string configDirectory, string outputDirectory)
     {
         var projects = configModel.Source;
         var references = configModel.References;
-        var outputFolder = configModel.Destination ?? "_api";
+
+        var outputFolder = Path.GetFullPath(Path.Combine(
+            string.IsNullOrEmpty(outputDirectory) ? Path.Combine(configDirectory, configModel.Output ?? "") : outputDirectory,
+            configModel.Destination ?? ""));
 
         var expandedFiles = GlobUtility.ExpandFileMapping(EnvironmentContext.BaseDirectory, projects);
         var expandedReferences = GlobUtility.ExpandFileMapping(EnvironmentContext.BaseDirectory, references);
@@ -120,7 +123,7 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config
             GlobalNamespaceId = configModel?.GlobalNamespaceId,
             MSBuildProperties = configModel?.MSBuildProperties,
             OutputFormat = configModel?.OutputFormat ?? default,
-            OutputFolder = Path.GetFullPath(Path.Combine(outputDirectory, outputFolder)),
+            OutputFolder = outputFolder,
             CodeSourceBasePath = configModel?.CodeSourceBasePath,
             DisableDefaultFilter = configModel?.DisableDefaultFilter ?? false,
             NoRestore = configModel?.NoRestore ?? false,

src/Docfx.Dotnet/MetadataJsonConfig.cs

@@ -83,10 +83,18 @@ internal class MetadataJsonItemConfig
 
     /// <summary>
     /// Defines the output folder of the generated metadata files.
+    /// Command line --output argument prepends this value.
     /// </summary>
     [JsonProperty("dest")]
     public string Destination { get; set; }
 
+    /// <summary>
+    /// Defines the output folder of the generated metadata files.
+    /// Command line --output argument override this value.
+    /// </summary>
+    [JsonProperty("output")]
+    public string Output { get; set; }
+
     /// <summary>
     /// Defines the output file format.
     /// </summary>

test/docfx.Snapshot.Tests/SamplesTest.cs

@@ -180,15 +180,16 @@ static string NormalizeHtml(string html)
         }
     }
 
-    [SnapshotFact]
+    [Fact]
     public async Task SeedMarkdown()
     {
         var samplePath = $"{s_samplesDir}/seed";
+        var outputPath = nameof(SeedMarkdown);
         Clean(samplePath);
 
-        Program.Main(new[] { "metadata", $"{samplePath}/docfx.json", "--outputFormat", "markdown", "--output", nameof(SeedMarkdown) });
+        Program.Main(new[] { "metadata", $"{samplePath}/docfx.json", "--outputFormat", "markdown", "--output", outputPath });
 
-        await VerifyDirectory($"{nameof(SeedMarkdown)}/obj/api", IncludeFile, fileScrubber: ScrubFile).AutoVerify(includeBuildServer: false);
+        await VerifyDirectory(outputPath, IncludeFile, fileScrubber: ScrubFile).AutoVerify(includeBuildServer: false);
     }
 
     [SnapshotFact]