protected void AddToToc(SplitPath path)
{
if (_options.UpdateToc)
{
_tocManager.AddToToc(path);
}
}
/*
## Initializing Page Specific Parameters
##
## There are a few built-in parameters that the theme can use. They are
## updated before processing each document by the method below. Refer to
## the documentation of the [PageParams](../CSWeave.Theme/PageParams.html)
## class for more information about the parameters.
*/
private void InitParams(SplitPath inputFile, SplitPath outputFile)
{
_params.Filename = outputFile.FileNameWithoutExtension;
_params.Root = outputFile.RelativeFileRoot;
_params.CurrentSection = _params.Toc.Flattened.FirstOrDefault(e =>
e.File == inputFile.FilePath);
}
/*
### Helper Functions
###
###The rest of the code in this class consist of helper functions which are
###called by the main generation methods. The function below copies an input
###file to the output directory.
*/
private void CopyFile(SplitPath inputFile)
{
var outputFile = _options.OutputPath + inputFile;
ConsoleOut("Copying file '{0}' to '{1}'",
inputFile.FilePath, outputFile.FilePath);
DirHelpers.Copy(!inputFile, outputFile.DirectoryName, true);
}
/*
### Output Path for a File
###
###For each input file we need to construct the output path. We take the base
###path from command line options and join it with the relative file path of
###the input file changing the extension simultaneously. We also check that the
###output directory exists, and create it when needed.
*/
protected SplitPath CreateOutputPath(SplitPath codeFile, string extension)
{
var outputFile = _options.OutputPath + codeFile.ChangeExtension(extension);
ConsoleOut("Generating {0} from file '{1}' into file '{2}'",
extension, codeFile.FilePath, outputFile.FilePath);
DirHelpers.EnsureExists(outputFile.DirectoryName);
return(outputFile);
}
/*
## Generating HTML from Markdown File
##
## Converting markdown file to HTML is somewhat simpler task. We perform
## mostly the same steps as with C# files, except that we don't need to
## iterate through a block list. We can convert the whole markdown file
## to HTML in one go.
*/
public void FromMarkdown(SplitPath inputFile, SplitPath outputFile)
{
InitParams(inputFile, outputFile);
var markdown = File.ReadAllText(!inputFile);
var template = ParseFrontMatter(markdown, !inputFile);
_params.Contents = Markdown.ToHtml(markdown, _pipeline);
using (var writer = File.CreateText(!outputFile))
writer.Write(_theme.RenderPage(template, _params));
}
/*
* Now we can enumerate the input files.
*/
protected IEnumerable <SplitPath> InputFiles()
{
var filtRegexes = FilterRegexes();
var files = from file in DirHelpers.Dir(_options.InputPath.BasePath, "*",
_options.Recursive)
let relPath = SplitPath.Split(_options.InputPath.BasePath, file)
where filtRegexes.Any(re => re.IsMatch(relPath.FilePath))
select relPath;
return(IndicesFirst(files));
}
/*
* The mirror operation of defining an ID is making a token clickable by
* surrounding it with an `<a>` tag. The target of the link is in the `href`
* attribute, which is determined by the function below. The link consists
* of the relative file path and the ID inside the file. The file path is
* always used, even if the link target is inside the same file.
*/
private string GetHrefForSymbol(ISymbol symbol)
{
var sref = symbol.DeclaringSyntaxReferences.First();
var reffile = SplitPath.Split(_options.InputPath.BasePath,
sref.SyntaxTree.FilePath);
var inputfile = SplitPath.Split(_options.InputPath.BasePath,
_document.FilePath);
return(Path.Combine(inputfile.RelativeFileRoot,
reffile.ChangeExtension("html").FilePath).Replace('\\', '/') +
"#" + GetSymbolId(symbol));
}
/*
* And then we can gather the C# source files. Most of the heavy lifting is
* delegated to the MSBuildHelper class. In addition to the file path we
* return also the Document object that contains syntactic and semantic
* information that the Roslyn compiler attaches to the source file.
*/
protected IEnumerable <Tuple <SplitPath, Document> > CSharpDocumentsInSolution(
SolutionFile solutionFile)
{
var workspace = MSBuildWorkspace.Create();
var solution = workspace.OpenSolutionAsync(_options.Solution).Result;
var filtRegexes = FilterRegexes();
return(from proj in MSBuildHelpers.LoadProjectsInSolution(solution, solutionFile)
from doc in proj.Documents
let relPath = SplitPath.Split(_options.InputPath.BasePath, doc.FilePath)
where filtRegexes.Any(re => re.IsMatch(relPath.FilePath))
select Tuple.Create(relPath, doc));
}
/*
## Adding New Sections
##
## Instead of adding a new entry to TOC while the documentation is being
## generated, we add it to a temporary list. This list is concatenated
## to the TOC before it is saved. If there is no file associated to the
## TOC (in which case the temporary list is null), then we don't need to
## do anything.
*/
public void AddToToc(SplitPath path)
{
if (_addedSections == null)
{
return;
}
var section = FindSectionForFile(path.FilePath, Toc.Contents) ??
_addedSections.FirstOrDefault(s => s.File == path.FilePath);
if (section == null)
{
_addedSections.Add(new Section()
{
Page = path.FileNameWithoutExtension,
File = path.FilePath,
Desc = "TODO! Add page description."
});
}
}
/*
## Generating HTML Page from Code File
##
## Once a source file has been split into blocks, we can give the block
## list and the input and output file paths to the FromCode method. This
## is where the HTML page is actually generated.
*/
public void FromCode(BlockList blocks, SplitPath inputFile, SplitPath outputFile)
{
/*
* First, we initialize the document-level parameters.
*/
InitParams(inputFile, outputFile);
/*
* If the first block in the list is a markdown block, then we need to
* check if it contains a front matter. We initialize the used template
* to null, which selects the default template. The setting can be then
* overridden in the front matter.
*/
string template = null;
var firstMdBlock = blocks.FirstOrDefault(b => b.Kind == BlockKind.Markdown);
if (firstMdBlock != null)
{
template = ParseFrontMatter(firstMdBlock.Contents, !inputFile);
}
/*
* Next, we iterate through the blocks, convert them to HTML, and finally
* assign the resulted string into the `Contents` parameter, so that the
* theme can access it.
*/
using (var writer = new StringWriter())
{
foreach (var block in blocks)
{
writer.Write(Markdown.ToHtml(block.Contents, _pipeline));
}
_params.Contents = writer.ToString();
}
/*
* As the last step, we render the page using the theme, and write the
* resulting HTML page to the output file.
*/
using (var writer = File.CreateText(!outputFile))
writer.Write(_theme.RenderPage(template, _params));
}
/*
* The methods below construct the block list for a source file and write them
* into an output file. Since the blocks already contain valid markdown, no
* further processing is needed.
*/
private void GenerateMarkdownFromCode(SplitPath codeFile)
{
SplitPath outputFile = CreateOutputPath(codeFile, _options.MarkdownExt);
OutputBlocks(CreateBlockList(!codeFile), !outputFile);
}
protected bool IsIndexFile(SplitPath file) => file.FileNameWithoutExtension.ToLower() == _indexFile;
protected bool IsMarkdownFile(SplitPath file) => file.Extension == _options.MarkdownExt;
/* * We need some helper functions to determine the type of a file. The type of a file * is deduced from its extension or from its name. */ protected bool IsSourceFile(SplitPath file) => file.Extension == _options.SourceExt;
private void GenerateHtmlFromCSharpDocument(SplitPath codeFile, Document document)
{
_generateHtml.FromCode(CreateBlockList(document), codeFile,
CreateOutputPath(codeFile, ".html"));
}
private void GenerateHtmlFromMarkdown(SplitPath mdFile)
{
_generateHtml.FromMarkdown(mdFile, CreateOutputPath(mdFile, ".html"));
}
private void GenerateMarkdownFromCSharpDocument(SplitPath codeFile, Document document)
{
SplitPath outputFile = CreateOutputPath(codeFile, _options.MarkdownExt);
OutputBlocks(CreateBlockList(document), !outputFile);
}
/*
* The rest of the methods are helper functions that process a single file
* at a time; first they split it to blocks, and then call HTMLGenerator
* to convert it to a HTML page.
*/
private void GenerateHtmlFromCodeFile(SplitPath codeFile)
{
_generateHtml.FromCode(CreateBlockList(!codeFile), codeFile,
CreateOutputPath(codeFile, ".html"));
}