private static BuildJsonConfig ParseOptions(BuildCommandOptions options)
{
var configFile = options.ConfigFile;
BuildJsonConfig config;
if (string.IsNullOrEmpty(configFile))
{
if (!File.Exists(DocAsCode.Constants.ConfigFileName))
{
if (options.Content == null && options.Resource == null)
{
throw new ArgumentException("Either provide config file or specify content files to start building documentation.");
}
else
{
config = new BuildJsonConfig();
MergeOptionsToConfig(options, ref config);
return config;
}
}
else
{
Logger.Log(LogLevel.Verbose, $"Config file {DocAsCode.Constants.ConfigFileName} is found.");
configFile = DocAsCode.Constants.ConfigFileName;
}
}
config = CommandUtility.GetConfig<BuildConfig>(configFile).Item;
if (config == null) throw new DocumentException($"Unable to find build subcommand config in file '{configFile}'.");
config.BaseDirectory = Path.GetDirectoryName(configFile);
MergeOptionsToConfig(options, ref config);
return config;
}
public BuildCommand(BuildCommandOptions options)
{
Config = ParseOptions(options);
if (Config.Templates == null || Config.Templates.Count == 0)
{
Config.Templates = new ListWithStringFallback { DocAsCode.Constants.DefaultTemplateName };
}
var assembly = typeof(Program).Assembly;
_templateManager = new TemplateManager(assembly, "Template", Config.Templates, Config.Themes, Config.BaseDirectory);
}
public BuildCommand(Options options, CommandContext context)
{
var buildCommandOptions = options.BuildCommand;
if (buildCommandOptions.IsHelp)
{
_helpMessage = HelpTextGenerator.GetHelpMessage(options, "build");
}
else
{
Config = MergeConfig(GetConfigFromOptions(buildCommandOptions), context);
}
if (!string.IsNullOrWhiteSpace(buildCommandOptions.Log)) Logger.RegisterListener(new ReportLogListener(buildCommandOptions.Log));
if (buildCommandOptions.LogLevel.HasValue) Logger.LogLevelThreshold = buildCommandOptions.LogLevel.Value;
}
private ParseResult InternalExec(BuildJsonConfig config, RunningContext context)
{
var parameters = ConfigToParameter(config);
if (parameters.Files.Count == 0)
{
return(new ParseResult(ResultLevel.Warning, "No files found, nothing is to be generated"));
}
try
{
_builder.Build(parameters);
}
catch (AggregateDocumentException aggEx)
{
return(new ParseResult(ResultLevel.Warning, "following document error:" + Environment.NewLine + string.Join(Environment.NewLine, from ex in aggEx.InnerExceptions select ex.Message)));
}
catch (DocumentException ex)
{
return(new ParseResult(ResultLevel.Warning, "document error:" + ex.Message));
}
var documentContext = DocumentBuildContext.DeserializeFrom(parameters.OutputBaseDir);
var assembly = typeof(Program).Assembly;
if (config.Templates == null || config.Templates.Count == 0)
{
config.Templates = new ListWithStringFallback {
Constants.DefaultTemplateName
};
}
// If RootOutput folder is specified from command line, use it instead of the base directory
var outputFolder = Path.Combine(config.OutputFolder ?? config.BaseDirectory ?? string.Empty, config.Destination ?? string.Empty);
using (var manager = new TemplateManager(assembly, "Template", config.Templates, config.Themes, config.BaseDirectory))
{
manager.ProcessTemplateAndTheme(documentContext, outputFolder, true);
}
// TODO: SEARCH DATA
if (config.Serve)
{
ServeCommand.Serve(outputFolder, config.Port);
}
return(ParseResult.SuccessResult);
}
private static DocumentBuildParameters ConfigToParameter(BuildJsonConfig config)
{
var parameters = new DocumentBuildParameters();
var baseDirectory = config.BaseDirectory ?? Environment.CurrentDirectory;
parameters.OutputBaseDir = Path.Combine(baseDirectory, "obj");
if (config.GlobalMetadata != null)
{
parameters.Metadata = config.GlobalMetadata.ToImmutableDictionary();
}
if (config.FileMetadata != null)
{
parameters.FileMetadata = ConvertToFileMetadataItem(baseDirectory, config.FileMetadata);
}
parameters.ExternalReferencePackages = GetFilesFromFileMapping(GlobUtility.ExpandFileMapping(baseDirectory, config.ExternalReference)).ToImmutableArray();
parameters.Files = GetFileCollectionFromFileMapping(baseDirectory,
Tuple.Create(DocumentType.Article, GlobUtility.ExpandFileMapping(baseDirectory, config.Content)),
Tuple.Create(DocumentType.Override, GlobUtility.ExpandFileMapping(baseDirectory, config.Overwrite)),
Tuple.Create(DocumentType.Resource, GlobUtility.ExpandFileMapping(baseDirectory, config.Resource)));
return(parameters);
}
private ParseResult InternalExec(BuildJsonConfig config, RunningContext context)
{
var parameters = ConfigToParameter(config);
if (parameters.Files.Count == 0) return new ParseResult(ResultLevel.Warning, "No files found, nothing is to be generated");
try
{
_builder.Build(parameters);
}
catch (AggregateDocumentException aggEx)
{
return new ParseResult(ResultLevel.Warning, "following document error:" + Environment.NewLine + string.Join(Environment.NewLine, from ex in aggEx.InnerExceptions select ex.Message));
}
catch (DocumentException ex)
{
return new ParseResult(ResultLevel.Warning, "document error:" + ex.Message);
}
var documentContext = DocumentBuildContext.DeserializeFrom(parameters.OutputBaseDir);
var assembly = typeof(Program).Assembly;
if (config.Templates == null || config.Templates.Count == 0)
{
config.Templates = new ListWithStringFallback { Constants.DefaultTemplateName };
}
// If RootOutput folder is specified from command line, use it instead of the base directory
var outputFolder = Path.Combine(config.OutputFolder ?? config.BaseDirectory ?? string.Empty, config.Destination ?? string.Empty);
using (var manager = new TemplateManager(assembly, "Template", config.Templates, config.Themes, config.BaseDirectory))
{
manager.ProcessTemplateAndTheme(documentContext, outputFolder, true);
}
// TODO: SEARCH DATA
if (config.Serve)
{
ServeCommand.Serve(outputFolder, config.Port);
}
return ParseResult.SuccessResult;
}
private BuildJsonConfig MergeConfig(BuildJsonConfig config, CommandContext context)
{
config.BaseDirectory = context?.BaseDirectory ?? config.BaseDirectory;
if (context?.SharedOptions != null)
{
config.OutputFolder = context.SharedOptions.RootOutputFolder ?? config.OutputFolder;
var templates = context.SharedOptions.Templates;
if (templates != null)
{
config.Templates = new ListWithStringFallback(templates);
}
var themes = context.SharedOptions.Themes;
if (themes != null)
{
config.Themes = new ListWithStringFallback(themes);
}
config.Force |= context.SharedOptions.ForceRebuild;
config.Serve |= context.SharedOptions.Serve;
config.Port = context.SharedOptions.Port?.ToString();
}
return(config);
}
public BuildCommand(Options options, CommandContext context)
{
var buildCommandOptions = options.BuildCommand;
if (buildCommandOptions.IsHelp)
{
_helpMessage = HelpTextGenerator.GetHelpMessage(options, "build");
}
else
{
Config = MergeConfig(GetConfigFromOptions(buildCommandOptions), context);
}
if (!string.IsNullOrWhiteSpace(buildCommandOptions.Log))
{
Logger.RegisterListener(new ReportLogListener(buildCommandOptions.Log));
}
if (buildCommandOptions.LogLevel.HasValue)
{
Logger.LogLevelThreshold = buildCommandOptions.LogLevel.Value;
}
}
public BuildCommand(BuildJsonConfig config, CommandContext context)
{
Config = MergeConfig(config, context);
}
private static void BuildDocumentWithPlugin(BuildJsonConfig config, string baseDirectory, string outputDirectory, string applicationBaseDirectory, string pluginDirectory)
{
AppDomain builderDomain = null;
try
{
var pluginConfig = Path.Combine(pluginDirectory, "docfx.plugins.config");
Logger.LogInfo($"Plug-in directory: {pluginDirectory}, configuration file: {pluginConfig}");
AppDomainSetup setup = new AppDomainSetup
{
ApplicationBase = applicationBaseDirectory,
PrivateBinPath = string.Join(";", applicationBaseDirectory, pluginDirectory),
ConfigurationFile = pluginConfig
};
builderDomain = AppDomain.CreateDomain("document builder domain", null, setup);
builderDomain.UnhandledException += (s, e) => { };
builderDomain.DoCallBack(new DocumentBuilderWrapper(config, baseDirectory, outputDirectory, pluginDirectory, new CrossAppDomainListener()).BuildDocument);
}
finally
{
if (builderDomain != null)
{
AppDomain.Unload(builderDomain);
}
}
}
private BuildJsonConfig MergeConfig(BuildJsonConfig config, CommandContext context)
{
config.BaseDirectory = context?.BaseDirectory ?? config.BaseDirectory;
if (context?.SharedOptions != null)
{
config.OutputFolder = context.SharedOptions.RootOutputFolder ?? config.OutputFolder;
var templates = context.SharedOptions.Templates;
if (templates != null) config.Templates = new ListWithStringFallback(templates);
var themes = context.SharedOptions.Themes;
if (themes != null) config.Themes = new ListWithStringFallback(themes);
config.Force |= context.SharedOptions.ForceRebuild;
config.Serve |= context.SharedOptions.Serve;
config.Port = context.SharedOptions.Port?.ToString();
}
return config;
}
private static DocumentBuildParameters ConfigToParameter(BuildJsonConfig config, string baseDirectory, string outputDirectory)
{
var parameters = new DocumentBuildParameters();
parameters.OutputBaseDir = outputDirectory;
if (config.GlobalMetadata != null) parameters.Metadata = config.GlobalMetadata.ToImmutableDictionary();
if (config.FileMetadata != null) parameters.FileMetadata = ConvertToFileMetadataItem(baseDirectory, config.FileMetadata);
parameters.ExternalReferencePackages = GetFilesFromFileMapping(GlobUtility.ExpandFileMapping(baseDirectory, config.ExternalReference)).ToImmutableArray();
parameters.Files = GetFileCollectionFromFileMapping(
baseDirectory,
Tuple.Create(DocumentType.Article, GlobUtility.ExpandFileMapping(baseDirectory, config.Content)),
Tuple.Create(DocumentType.Override, GlobUtility.ExpandFileMapping(baseDirectory, config.Overwrite)),
Tuple.Create(DocumentType.Resource, GlobUtility.ExpandFileMapping(baseDirectory, config.Resource)));
parameters.ExportViewModel = config.ExportViewModel == true;
parameters.ExportRawModel = config.ExportRawModel == true;
return parameters;
}
public static void BuildDocument(BuildJsonConfig config, string baseDirectory, string outputDirectory, string pluginDirectory)
{
try
{
var templateManager = new TemplateManager(typeof(DocumentBuilderWrapper).Assembly, "Template", config.Templates, config.Themes, config.BaseDirectory);
using (var builder = new DocumentBuilder(LoadPluginAssemblies(pluginDirectory)))
{
var parameters = ConfigToParameter(config, baseDirectory, outputDirectory);
if (parameters.Files.Count == 0)
{
Logger.LogWarning("No files found, nothing is to be generated");
return;
}
using (var processor = templateManager.GetTemplateProcessor())
{
parameters.TemplateCollection = processor.Templates;
processor.ProcessDependencies(parameters.OutputBaseDir);
builder.Build(parameters);
}
}
}
catch (DocumentException ex)
{
Logger.LogWarning("Document error occurs:" + ex.Message);
}
catch (Exception ex)
{
Logger.LogError(ex.ToString());
}
}
public DocumentBuilderWrapper(BuildJsonConfig config, string baseDirectory, string outputDirectory, string pluginDirectory, CrossAppDomainListener listener)
{
if (config == null)
{
throw new ArgumentNullException(nameof(config));
}
_pluginDirectory = pluginDirectory;
_baseDirectory = baseDirectory;
_outputDirectory = outputDirectory;
_config = config;
_listener = listener;
}
private static BuildJsonConfig GetConfigFromOptions(BuildCommandOptions options)
{
string configFile = options.ConfigFile;
if (string.IsNullOrEmpty(configFile) && options.Content == null && options.Resource == null)
{
if (!File.Exists(Constants.ConfigFileName))
{
throw new ArgumentException("Either provide config file or specify content files to start building documentation.");
}
else
{
Logger.Log(LogLevel.Info, $"Config file {Constants.ConfigFileName} found, start building...");
configFile = Constants.ConfigFileName;
}
}
BuildJsonConfig config;
if (!string.IsNullOrEmpty(configFile))
{
var command = (BuildCommand)CommandFactory.ReadConfig(configFile, null).Commands.FirstOrDefault(s => s is BuildCommand);
if (command == null)
{
throw new ApplicationException($"Unable to find {CommandType.Build} subcommand config in file '{Constants.ConfigFileName}'.");
}
config = command.Config;
config.BaseDirectory = Path.GetDirectoryName(configFile);
}
else
{
config = new BuildJsonConfig();
}
config.OutputFolder = options.OutputFolder;
string optionsBaseDirectory = Environment.CurrentDirectory;
// Override config file with options from command line
if (options.Templates != null && options.Templates.Count > 0)
{
config.Templates = new ListWithStringFallback(options.Templates);
}
if (options.Themes != null && options.Themes.Count > 0)
{
config.Themes = new ListWithStringFallback(options.Themes);
}
if (!string.IsNullOrEmpty(options.OutputFolder))
{
config.Destination = Path.GetFullPath(Path.Combine(options.OutputFolder, config.Destination ?? string.Empty));
}
if (options.Content != null)
{
if (config.Content == null)
{
config.Content = new FileMapping(new FileMappingItem());
}
config.Content.Add(new FileMappingItem()
{
Files = new FileItems(options.Content), CurrentWorkingDirectory = optionsBaseDirectory
});
}
if (options.Resource != null)
{
if (config.Resource == null)
{
config.Resource = new FileMapping(new FileMappingItem());
}
config.Resource.Add(new FileMappingItem()
{
Files = new FileItems(options.Resource), CurrentWorkingDirectory = optionsBaseDirectory
});
}
if (options.Overwrite != null)
{
if (config.Overwrite == null)
{
config.Overwrite = new FileMapping(new FileMappingItem());
}
config.Overwrite.Add(new FileMappingItem()
{
Files = new FileItems(options.Overwrite), CurrentWorkingDirectory = optionsBaseDirectory
});
}
if (options.ExternalReference != null)
{
if (config.ExternalReference == null)
{
config.ExternalReference = new FileMapping(new FileMappingItem());
}
config.ExternalReference.Add(new FileMappingItem()
{
Files = new FileItems(options.ExternalReference), CurrentWorkingDirectory = optionsBaseDirectory
});
}
if (options.Serve)
{
config.Serve = options.Serve;
}
if (options.Port.HasValue)
{
config.Port = options.Port.Value.ToString();
}
return(config);
}
public BuildCommand(BuildJsonConfig config, CommandContext context)
{
Config = MergeConfig(config, context);
}
private static DocumentBuildParameters ConfigToParameter(BuildJsonConfig config)
{
var parameters = new DocumentBuildParameters();
var baseDirectory = config.BaseDirectory ?? Environment.CurrentDirectory;
parameters.OutputBaseDir = Path.Combine(baseDirectory, "obj");
if (config.GlobalMetadata != null) parameters.Metadata = config.GlobalMetadata.ToImmutableDictionary();
if (config.FileMetadata != null) parameters.FileMetadata = ConvertToFileMetadataItem(baseDirectory, config.FileMetadata);
parameters.ExternalReferencePackages = GetFilesFromFileMapping(GlobUtility.ExpandFileMapping(baseDirectory, config.ExternalReference)).ToImmutableArray();
parameters.Files = GetFileCollectionFromFileMapping(baseDirectory,
Tuple.Create(DocumentType.Article, GlobUtility.ExpandFileMapping(baseDirectory, config.Content)),
Tuple.Create(DocumentType.Override, GlobUtility.ExpandFileMapping(baseDirectory, config.Overwrite)),
Tuple.Create(DocumentType.Resource, GlobUtility.ExpandFileMapping(baseDirectory, config.Resource)));
return parameters;
}
private static BuildJsonConfig GetConfigFromOptions(BuildCommandOptions options)
{
string configFile = options.ConfigFile;
if (string.IsNullOrEmpty(configFile) && options.Content == null && options.Resource == null)
{
if (!File.Exists(Constants.ConfigFileName))
{
throw new ArgumentException("Either provide config file or specify content files to start building documentation.");
}
else
{
Logger.Log(LogLevel.Info, $"Config file {Constants.ConfigFileName} found, start building...");
configFile = Constants.ConfigFileName;
}
}
BuildJsonConfig config;
if (!string.IsNullOrEmpty(configFile))
{
var command = (BuildCommand)CommandFactory.ReadConfig(configFile, null).Commands.FirstOrDefault(s => s is BuildCommand);
if (command == null) throw new ApplicationException($"Unable to find {CommandType.Build} subcommand config in file '{Constants.ConfigFileName}'.");
config = command.Config;
config.BaseDirectory = Path.GetDirectoryName(configFile);
}
else
{
config = new BuildJsonConfig();
}
config.OutputFolder = options.OutputFolder;
string optionsBaseDirectory = Environment.CurrentDirectory;
// Override config file with options from command line
if (options.Templates != null && options.Templates.Count > 0) config.Templates = new ListWithStringFallback(options.Templates);
if (options.Themes != null && options.Themes.Count > 0) config.Themes = new ListWithStringFallback(options.Themes);
if (!string.IsNullOrEmpty(options.OutputFolder)) config.Destination = Path.GetFullPath(Path.Combine(options.OutputFolder, config.Destination ?? string.Empty));
if (options.Content != null)
{
if (config.Content == null)
config.Content = new FileMapping(new FileMappingItem());
config.Content.Add(new FileMappingItem() { Files = new FileItems(options.Content), CurrentWorkingDirectory = optionsBaseDirectory });
}
if (options.Resource != null)
{
if (config.Resource == null)
config.Resource = new FileMapping(new FileMappingItem());
config.Resource.Add(new FileMappingItem() { Files = new FileItems(options.Resource), CurrentWorkingDirectory = optionsBaseDirectory });
}
if (options.Overwrite != null)
{
if (config.Overwrite == null)
config.Overwrite = new FileMapping(new FileMappingItem());
config.Overwrite.Add(new FileMappingItem() { Files = new FileItems(options.Overwrite), CurrentWorkingDirectory = optionsBaseDirectory });
}
if (options.ExternalReference != null)
{
if (config.ExternalReference == null)
config.ExternalReference = new FileMapping(new FileMappingItem());
config.ExternalReference.Add(new FileMappingItem() { Files = new FileItems(options.ExternalReference), CurrentWorkingDirectory = optionsBaseDirectory });
}
if (options.Serve) config.Serve = options.Serve;
if (options.Port.HasValue) config.Port = options.Port.Value.ToString();
return config;
}
private static void MergeOptionsToConfig(BuildCommandOptions options, ref BuildJsonConfig config)
{
// base directory for content from command line is current directory
// e.g. C:\folder1>docfx build folder2\docfx.json --content "*.cs"
// for `--content "*.cs*`, base directory should be `C:\folder1`
string optionsBaseDirectory = Environment.CurrentDirectory;
config.OutputFolder = options.OutputFolder;
// Override config file with options from command line
if (options.Templates != null && options.Templates.Count > 0) config.Templates = new ListWithStringFallback(options.Templates);
if (options.Themes != null && options.Themes.Count > 0) config.Themes = new ListWithStringFallback(options.Themes);
if (!string.IsNullOrEmpty(options.OutputFolder)) config.Destination = Path.GetFullPath(Path.Combine(options.OutputFolder, config.Destination ?? string.Empty));
if (options.Content != null)
{
if (config.Content == null) config.Content = new FileMapping(new FileMappingItem());
config.Content.Add(new FileMappingItem() { Files = new FileItems(options.Content), SourceFolder = optionsBaseDirectory });
}
if (options.Resource != null)
{
if (config.Resource == null) config.Resource = new FileMapping(new FileMappingItem());
config.Resource.Add(new FileMappingItem() { Files = new FileItems(options.Resource), SourceFolder = optionsBaseDirectory });
}
if (options.Overwrite != null)
{
if (config.Overwrite == null) config.Overwrite = new FileMapping(new FileMappingItem());
config.Overwrite.Add(new FileMappingItem() { Files = new FileItems(options.Overwrite), SourceFolder = optionsBaseDirectory });
}
if (options.ExternalReference != null)
{
if (config.ExternalReference == null) config.ExternalReference = new FileMapping(new FileMappingItem());
config.ExternalReference.Add(new FileMappingItem() { Files = new FileItems(options.ExternalReference), SourceFolder = optionsBaseDirectory });
}
if (options.Serve) config.Serve = options.Serve;
if (options.Port.HasValue) config.Port = options.Port.Value.ToString();
config.Force |= options.ForceRebuild;
config.ExportRawModel |= options.ExportRawModel;
config.ExportViewModel |= options.ExportViewModel;
var fileMetadata = GetFileMetadataFromOption(options.FileMetadataFilePath);
if (fileMetadata != null) config.FileMetadata = fileMetadata;
var globalMetadata = GetGlobalMetadataFromOption(options.GlobalMetadata, options.GlobalMetadataFilePath);
if (globalMetadata != null) config.GlobalMetadata = globalMetadata;
}
