feat: add overridable metadata output json config

Author: yufeih

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/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,10 @@ 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 expandedFiles = GlobUtility.ExpandFileMapping(EnvironmentContext.BaseDirectory, projects);
         var expandedReferences = GlobUtility.ExpandFileMapping(EnvironmentContext.BaseDirectory, references);
@@ -120,7 +119,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 = Path.GetFullPath(Path.Combine(configDirectory, outputDirectory ?? configModel.Output ?? "_api", configModel.Destination ?? "")),
             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>

src/docfx/Models/MetadataCommand.cs

@@ -14,35 +14,14 @@ public override int Execute([NotNull] CommandContext context, [NotNull] Metadata
     {
         return CommandHelper.Run(options, () =>
         {
-            var config = ParseOptions(options, out var baseDirectory, out var outputFolder);
-            DotnetApiCatalog.Exec(config, new(), baseDirectory, outputFolder).GetAwaiter().GetResult();
+            var (config, baseDirectory) = CommandHelper.GetConfig<MetadataConfig>(options.Config);
+            MergeOptionsToConfig(options, config);
+            DotnetApiCatalog.Exec(config.Item, new(), baseDirectory, options.OutputFolder).GetAwaiter().GetResult();
         });
     }
 
-    private static MetadataJsonConfig ParseOptions(MetadataCommandOptions options, out string baseDirectory, out string outputFolder)
+    private static void MergeOptionsToConfig(MetadataCommandOptions options, MetadataConfig config)
     {
-        MetadataConfig config;
-
-        if (options.Config != null && !string.Equals(Path.GetFileName(options.Config), DataContracts.Common.Constants.ConfigFileName, StringComparison.OrdinalIgnoreCase))
-        {
-            config = new()
-            {
-                Item = new()
-                {
-                    new()
-                    {
-                        Destination = options.OutputFolder,
-                        Source = new FileMapping(new FileMappingItem(new[]{ options.Config })) { Expanded = true },
-                    }
-                }
-            };
-            baseDirectory = Directory.GetCurrentDirectory();
-        }
-        else
-        {
-            (config, baseDirectory) = CommandHelper.GetConfig<MetadataConfig>(options.Config);
-        }
-
         var msbuildProperties = ResolveMSBuildProperties(options);
         foreach (var item in config.Item)
         {
@@ -75,10 +54,6 @@ private static MetadataJsonConfig ParseOptions(MetadataCommandOptions options, o
                 }
             }
         }
-
-        outputFolder = options.OutputFolder;
-
-        return config.Item;
     }
 
     private static Dictionary<string, string> ResolveMSBuildProperties(MetadataCommandOptions options)

test/docfx.Snapshot.Tests/SamplesTest.cs

@@ -188,7 +188,7 @@ public async Task SeedMarkdown()
 
         Program.Main(new[] { "metadata", $"{samplePath}/docfx.json", "--outputFormat", "markdown", "--output", nameof(SeedMarkdown) });
 
-        await VerifyDirectory($"{nameof(SeedMarkdown)}/obj/api", IncludeFile, fileScrubber: ScrubFile).AutoVerify(includeBuildServer: false);
+        await VerifyDirectory($"{nameof(SeedMarkdown)}", IncludeFile, fileScrubber: ScrubFile).AutoVerify(includeBuildServer: false);
     }
 
     [SnapshotFact]