private void WeaveFromCSharpDocument(SplitPath codeFile,
Document document)
{
SplitPath outputFile = CreateOutputPath(codeFile, _options.MarkdownExt);
OutputBlocks(BlockListFromDocument(document), !outputFile);
}
private 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](../LiterateCS.Theme/PageParams.html)
## class for more information about the parameters.
*/
private void InitParams(SplitPath inputFile, SplitPath outputFile)
{
_params.Filename = outputFile.FileNameWithoutExtension;
_params.Root = outputFile.RelativePathToRoot;
_params.CurrentSection = _params.Toc.Flattened.FirstOrDefault(e =>
e.File == inputFile.FilePath);
}
/*
* Now we can enumerate the input files.
*/
protected IEnumerable <SplitPath> InputFiles()
{
var filtRegexes = FilterRegexes();
return(from file in DirHelpers.Dir(_options.InputPath.BasePath, "*", true)
let relPath = SplitPath.Split(_options.InputPath.BasePath, file)
where filtRegexes.Any(re => re.IsMatch(relPath.FilePath))
select relPath);
}
/*
### 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);
}
/*
* 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.RelativePathToRoot,
reffile.ChangeExtension("html").FilePath).Replace('\\', '/') +
"#" + GetSymbolId(symbol));
}
/*
### Enumerating Files in Solution
###When a solution file is used as an input, C# files are retrieved in a different way.
###They are enumerated using the Roslyn
###[workspace](https://github.com/dotnet/roslyn/wiki/Roslyn-Overview#working-with-a-workspace).
*/
protected IEnumerable <Tuple <SplitPath, Document> > CSharpDocumentsInSolution()
{
var solution = BuildSolution();
var filtRegexes = FilterRegexes();
return(from proj in CompileProjectsInSolution(solution)
from doc in proj.Documents
let relPath = SplitPath.Split(_options.InputPath.BasePath, doc.FilePath)
where filtRegexes.Any(re => re.IsMatch(relPath.FilePath)) &&
!(relPath.FilePath.EndsWith("AssemblyAttributes.cs") ||
relPath.FilePath.EndsWith("AssemblyInfo.cs"))
select Tuple.Create(relPath, doc));
}
/*
## 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 `Execute` method. This
## is where the HTML page is actually generated.
*/
public void Execute(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(
GetFrontMatter(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));
}
/*
## 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."
});
}
}
/*
* 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 WeaveFromCodeFile(SplitPath codeFile)
{
_generateHtml.Execute(BlockListFromCode(!codeFile), codeFile,
CreateOutputPath(codeFile, ".html"));
}
private void WeaveFromMarkdown(SplitPath mdFile)
{
_generateHtml.Execute(BlockListFromMarkdown(!mdFile), mdFile,
CreateOutputPath(mdFile, ".html"));
}
private void WeaveFromCSharpDocument(SplitPath codeFile, Document document)
{
_generateHtml.Execute(BlockListFromDocument(document), codeFile,
CreateOutputPath(codeFile, ".html"));
}
private void WeaveFromCode(SplitPath codeFile)
{
SplitPath outputFile = CreateOutputPath(codeFile, _options.MarkdownExt);
OutputBlocks(BlockListFromCode(!codeFile), !outputFile);
}
/*
### Weaving the Output
###The rest of the code in this class consist of helper functions which
###split the input files to blocks and compile the output from them.
###Since the blocks already contain valid markdown, no further processing
###is needed to transform them.
*/
private void WeaveFromMarkdown(SplitPath mdFile)
{
SplitPath outputFile = CreateOutputPath(mdFile, _options.MarkdownExt);
OutputBlocks(BlockListFromMarkdown(!mdFile), !outputFile);
}
protected bool IsMarkdownFile(SplitPath file) => file.Extension == _options.MarkdownExt;
/* * Finally 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;
