| public static ToDisplayPath ( this path ) : string | ||
| path | this | |
| return | string | |
private static string ExportModel(object model, string modelFileRelativePath, ExportSettings settings)
{
if (model == null)
{
return(null);
}
var outputFolder = settings.OutputFolder;
string modelPath = Path.Combine(outputFolder ?? string.Empty, settings.PathRewriter(modelFileRelativePath));
JsonUtility.Serialize(modelPath, model);
return(TypeForwardedToStringExtension.ToDisplayPath(modelPath));
}
private void PrepareBuild(DocumentBuildContext context, IEnumerable <HostService> hostServices)
{
var incrementalContext = context.IncrementalBuildContext;
var lbv = incrementalContext?.LastBuildVersionInfo;
var cbv = incrementalContext?.CurrentBuildVersionInfo;
if (ShouldTraceIncrementalInfo)
{
var ldg = lbv?.Dependency;
var cdg = cbv.Dependency;
if (ldg != null)
{
// reregister dependency types from last dependency graph
using (new LoggerPhaseScope("RegisterDependencyTypeFromLastBuild", true))
{
cdg.RegisterDependencyType(ldg.DependencyTypes.Values);
}
// restore dependency graph from last dependency graph
using (new LoggerPhaseScope("ReportDependencyFromLastBuild", true))
{
cdg.ReportDependency(from r in ldg.ReportedBys
from i in ldg.GetDependencyReportedBy(r)
select i);
}
}
}
foreach (var hostService in hostServices)
{
hostService.SourceFiles = context.AllSourceFiles;
foreach (var m in hostService.Models)
{
if (m.LocalPathFromRepoRoot == null)
{
m.LocalPathFromRepoRoot = TypeForwardedToStringExtension.ToDisplayPath(Path.Combine(m.BaseDir, m.File));
}
if (m.LocalPathFromRoot == null)
{
m.LocalPathFromRoot = TypeForwardedToStringExtension.ToDisplayPath(Path.Combine(m.BaseDir, m.File));
}
}
if (ShouldTraceIncrementalInfo)
{
hostService.DependencyGraph = cbv.Dependency;
using (new LoggerPhaseScope("RegisterDependencyTypeFromProcessor", true))
{
RegisterDependencyType(hostService);
}
}
}
}
private static LoggerFileScope GetFileScope(ImmutableStack <string> parents)
{
if (!parents.IsEmpty)
{
var path = TypeForwardedToStringExtension.ToDisplayPath(parents.Peek());
if (!string.IsNullOrEmpty(path))
{
return(new LoggerFileScope(path));
}
}
return(null);
}
public void Exec(SubCommandRunningContext context)
{
string outputFolder = null;
try
{
var config = new DefaultConfigModel();
var questionContext = new QuestionContext
{
Quiet = _options.Quiet
};
foreach (var question in _selectorQuestions)
{
question.Process(config, questionContext);
}
foreach (var question in _overallQuestion)
{
question.Process(config, questionContext);
}
if (questionContext.ContainsMetadata)
{
foreach (var question in _metadataQuestions)
{
question.Process(config, questionContext);
}
}
foreach (var question in _buildQuestions)
{
question.Process(config, questionContext);
}
if (_options.OnlyConfigFile)
{
GenerateConfigFile(_options.OutputFolder, config);
}
else
{
outputFolder = TypeForwardedToStringExtension.ToDisplayPath(Path.GetFullPath(string.IsNullOrEmpty(_options.OutputFolder) ? DefaultOutputFolder : _options.OutputFolder));
GenerateSeedProject(outputFolder, config);
}
}
catch (Exception e)
{
throw new DocfxInitException($"Error with init docfx project under \"{outputFolder}\" : {e.Message}", e);
}
}
private static void GenerateConfigFile(string outputFolder, object config)
{
var path = TypeForwardedToStringExtension.ToDisplayPath(Path.Combine(outputFolder ?? string.Empty, ConfigName));
if (File.Exists(path))
{
if (!ProcessOverwriteQuestion($"Config file \"{path}\" already exists, do you want to overwrite this file?"))
{
return;
}
}
SaveConfigFile(path, config);
$"Successfully generated default docfx config file to {path}".WriteLineToConsole(ConsoleColor.Green);
}
public override FileModel Load(FileAndType file, ImmutableDictionary <string, object> metadata)
{
switch (file.Type)
{
case DocumentType.Article:
var filePath = Path.Combine(file.BaseDir, file.File);
var swaggerContent = File.ReadAllText(filePath);
var swagger = SwaggerJsonParser.Parse(swaggerContent);
swagger.Metadata[DocumentTypeKey] = RestApiDocumentType;
swagger.Raw = swaggerContent;
CheckOperationId(swagger, file.File);
var repoInfo = GitUtility.GetGitDetail(filePath);
if (repoInfo != null)
{
swagger.Metadata["source"] = new SourceDetail()
{
Remote = repoInfo
};
}
swagger.Metadata = MergeMetadata(swagger.Metadata, metadata);
var vm = SwaggerModelConverter.FromSwaggerModel(swagger);
var displayLocalPath = TypeForwardedToPathUtility.MakeRelativePath(EnvironmentContext.BaseDirectory, file.FullPath);
return(new FileModel(file, vm, serializer: Environment.Is64BitProcess?null: new BinaryFormatter())
{
Uids = new[] { new UidDefinition(vm.Uid, displayLocalPath) }
.Concat(from item in vm.Children select new UidDefinition(item.Uid, displayLocalPath))
.Concat(from tag in vm.Tags select new UidDefinition(tag.Uid, displayLocalPath)).ToImmutableArray(),
LocalPathFromRepoRoot = repoInfo?.RelativePath ?? TypeForwardedToStringExtension.ToDisplayPath(filePath),
LocalPathFromRoot = displayLocalPath
});
case DocumentType.Overwrite:
// TODO: Refactor current behavior that overwrite file is read multiple times by multiple processors
return(OverwriteDocumentReader.Read(file));
default:
throw new NotSupportedException();
}
}
public override FileModel Load(FileAndType file, ImmutableDictionary <string, object> metadata)
{
string uid = null;
Dictionary <string, object> content = null;
var metafile = Path.Combine(file.BaseDir, file.File.TrimEnd('.') + ".meta");
if (File.Exists(metafile))
{
content = YamlUtility.Deserialize <Dictionary <string, object> >(metafile);
if (content != null)
{
foreach (var item in metadata)
{
if (!content.ContainsKey(item.Key))
{
content[item.Key] = item.Value;
}
if (item.Key == Constants.PropertyName.Uid)
{
uid = item.Value as string;
}
}
}
}
if (content == null)
{
content = metadata.ToDictionary(p => p.Key, p => p.Value);
}
var filePath = Path.Combine(file.BaseDir, file.File);
var repoDetail = GitUtility.GetGitDetail(filePath);
var displayLocalPath = TypeForwardedToPathUtility.MakeRelativePath(EnvironmentContext.BaseDirectory, file.FullPath);
return(new FileModel(file, content)
{
Uids = string.IsNullOrEmpty(uid) ? ImmutableArray <UidDefinition> .Empty : ImmutableArray <UidDefinition> .Empty.Add(new UidDefinition(uid, displayLocalPath)),
LocalPathFromRepoRoot = repoDetail?.RelativePath ?? TypeForwardedToStringExtension.ToDisplayPath(Path.Combine(file.BaseDir, file.File)),
LocalPathFromRoot = displayLocalPath
});
}
public void ProcessTocWithCircularReferenceShouldFail()
{
var referencedToc = _fileCreator.CreateFile($@"
- name: Topic
href: TOC.md
", FileType.YamlToc, "sub1");
var subToc = _fileCreator.CreateFile($@"
#Topic
##[ReferencedToc](Toc.yml)
", FileType.MarkdownToc, "sub1");
var content = $@"
- name: Topic1
href: {subToc}
";
var toc = _fileCreator.CreateFile(content, FileType.YamlToc);
FileCollection files = new FileCollection(_inputFolder);
files.Add(DocumentType.Article, new[] { toc, subToc });
var e = Assert.Throws <DocumentException>(() => BuildDocument(files));
Assert.Equal($"Circular reference to {TypeForwardedToStringExtension.ToDisplayPath(Path.GetFullPath(Path.Combine(_inputFolder, subToc)))} is found in {TypeForwardedToStringExtension.ToDisplayPath(Path.GetFullPath(Path.Combine(_inputFolder, referencedToc)))}", e.Message, true);
}
private static void GenerateSeedProject(string outputFolder, DefaultConfigModel config)
{
if (Directory.Exists(outputFolder))
{
if (!ProcessOverwriteQuestion($"Output folder \"{outputFolder}\" already exists. Do you still want to generate files into this folder? You can use -o command option to specify the folder name"))
{
return;
}
}
else
{
Directory.CreateDirectory(outputFolder);
}
// 1. Create default files
var srcFolder = Path.Combine(outputFolder, "src");
var apiFolder = Path.Combine(outputFolder, "api");
var apidocFolder = Path.Combine(outputFolder, "apidoc");
var articleFolder = Path.Combine(outputFolder, "articles");
var imageFolder = Path.Combine(outputFolder, "images");
var folders = new string[] { srcFolder, apiFolder, apidocFolder, articleFolder, imageFolder };
foreach (var folder in folders)
{
Directory.CreateDirectory(folder);
$"Created folder {TypeForwardedToStringExtension.ToDisplayPath(folder)}".WriteLineToConsole(ConsoleColor.Gray);
}
// 2. Create default files
// a. toc.yml
// b. index.md
// c. articles/toc.yml
// d. articles/index.md
// e. .gitignore
// f. api/.gitignore
// TODO: move api/index.md out to some other folder
var tocYaml = Tuple.Create("toc.yml", @"- name: Articles
href: articles/
- name: Api Documentation
href: api/
homepage: api/index.md
");
var indexMarkdownFile = Tuple.Create("index.md", @"# This is the **HOMEPAGE**.
Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
## Quick Start Notes:
1. Add images to the *images* folder if the file is referencing an image.
");
var apiTocFile = Tuple.Create("api/toc.yml", @"- name: TO BE REPLACED
- href: index.md
");
var apiIndexFile = Tuple.Create("api/index.md", @"# PLACEHOLDER
TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
");
var articleTocFile = Tuple.Create("articles/toc.yml", @"- name: Introduction
href: intro.md
");
var articleMarkdownFile = Tuple.Create("articles/intro.md", @"# Add your introductions here!
");
var gitignore = Tuple.Create(".gitignore", $@"###############
# folder #
###############
/**/DROP/
/**/TEMP/
/**/packages/
/**/bin/
/**/obj/
{config.Build.Destination}
");
var apiGitignore = Tuple.Create("api/.gitignore", $@"###############
# temp file #
###############
*.yml
");
var files = new Tuple <string, string>[] { tocYaml, indexMarkdownFile, apiTocFile, apiIndexFile, articleTocFile, articleMarkdownFile, gitignore, apiGitignore };
foreach (var file in files)
{
var filePath = Path.Combine(outputFolder, file.Item1);
var content = file.Item2;
var dir = Path.GetDirectoryName(filePath);
if (!string.IsNullOrEmpty(dir))
{
Directory.CreateDirectory(dir);
}
File.WriteAllText(filePath, content);
$"Created File {TypeForwardedToStringExtension.ToDisplayPath(filePath)}".WriteLineToConsole(ConsoleColor.Gray);
}
// 2. Create docfx.json
var path = Path.Combine(outputFolder ?? string.Empty, ConfigName);
SaveConfigFile(path, config);
$"Created config file {TypeForwardedToStringExtension.ToDisplayPath(path)}".WriteLineToConsole(ConsoleColor.Gray);
$"Successfully generated default docfx project to {TypeForwardedToStringExtension.ToDisplayPath(outputFolder)}".WriteLineToConsole(ConsoleColor.Green);
"Please run:".WriteLineToConsole(ConsoleColor.Gray);
$"\tdocfx \"{TypeForwardedToStringExtension.ToDisplayPath(path)}\" --serve".WriteLineToConsole(ConsoleColor.White);
"To generate a default docfx website.".WriteLineToConsole(ConsoleColor.Gray);
}
private Dictionary <string, string> GetListContent(XPathNavigator navigator, string xpath, string contentType, ITripleSlashCommentParserContext context)
{
var iterator = navigator.Select(xpath);
var result = new Dictionary <string, string>();
if (iterator == null)
{
return(result);
}
foreach (XPathNavigator nav in iterator)
{
string name = nav.GetAttribute("name", string.Empty);
string description = GetXmlValue(nav);
if (!string.IsNullOrEmpty(name))
{
if (result.ContainsKey(name))
{
string path = context.Source.Remote != null?Path.Combine(context.Source.Remote.LocalWorkingDirectory, context.Source.Remote.RelativePath) : context.Source.Path;
Logger.LogWarning($"Duplicate {contentType} '{name}' found in comments, the latter one is ignored.", null, TypeForwardedToStringExtension.ToDisplayPath(path), context.Source.StartLine.ToString());
}
else
{
result.Add(name, description);
}
}
}
return(result);
}