/// <summary>
/// Append a section to the documentation containing the targets parameters by using the
/// xml based help. Therefore the help section "Parameter" is used.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendParameterSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target)
{
if (!target.Help.ContainsSection(MsBuildHelpSections.Parameter,
StringComparison.OrdinalIgnoreCase))
{
return;
}
IPrintableDocumentChapter parameterChapter = targetOverviewDocument.AddNewChapter("Parameters");
foreach (IMsBuildElementHelpParagraph parameterHelpParagraph in
target.Help.LookUp(MsBuildHelpSections.Parameter, StringComparison.OrdinalIgnoreCase))
{
IPrintableDocumentParagraph parameterParagraph =
parameterChapter.AddNewParagraph(
string.Format(CultureInfo.InvariantCulture, "Parameter {0}",
parameterHelpParagraph.Additional)
);
IPrintableDocumentChapterStringContent parameterSectionBody =
parameterParagraph.AddNewContent <IPrintableDocumentChapterStringContent>();
parameterSectionBody.Content = parameterHelpParagraph.Content;
}
}
/// <summary>
/// Append a section to the documentation containing the targets error handling by using the
/// MsBuild Task "OnError". The task is read from the target content if exists.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendErrorHandlingSection(IPrintableDocument targetOverviewDocument,
IMsBuildTarget target)
{
if (target.OnErrorTargets == null ||
target.OnErrorTargets?.Count == 0)
{
return;
}
IPrintableDocumentChapter errorHandlingChapter =
targetOverviewDocument.AddNewChapter("Error Handling");
IPrintableDocumentChapterStringContent chapterContent =
errorHandlingChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
StringBuilder builder = new StringBuilder();
builder.AppendLine(
string.Format(CultureInfo.InvariantCulture,
"This chapter contains an description of the error handling of this target. All listed targets are executed after an error occured in the target {0}.",
target.Name)
);
builder.AppendLine();
foreach (var onErrorTarget in target.OnErrorTargets)
{
builder.AppendLine(string.Format(CultureInfo.InvariantCulture, " - {0}", onErrorTarget));
}
chapterContent.Content = builder.ToString();
}
/// <summary>
/// Appends a section to the documentation body containing all information about
/// the given properties. Only properties are considered that are settable from
/// outside the MSBuild target file.
/// </summary>
/// <param name="properties">List of properties that should be represented by the section</param>
private void AppendGlobalPropertySection(IList <IMsBuildProperty> properties)
{
if (properties == null || !properties.Any(p => p.HasPublicSetter))
{
return;
}
var propertyChapter = _outputDocument.AddNewChapter("Overwriteable Properties");
IPrintableDocumentChapterStringContent paragraph =
propertyChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
paragraph.Content =
$"Contains all properties in {_outputDocument.Title} that could be overwritten from outside the document.";
var propertyTable = propertyChapter.AddNewContent <IPrintableParagraphTable>();
propertyTable.WithHeaders("Property", "Description", "Condition");
foreach (var property in properties.Where(p => p.HasPublicSetter))
{
propertyTable.WithRow(property.Name,
string.Join(Environment.NewLine, GetPropertySynopsisOrDescription(property)?.Content),
property.Condition);
}
}
/// <summary>
/// Appends a section to the documentation body containing all information about
/// the given properties. Only properties are considered that are not settable from
/// outside the MSBuild target file.
/// </summary>
/// <param name="properties">List of properties that should be represented by the section</param>
private void AppendPropertySection(IList <IMsBuildProperty> properties)
{
if (properties == null || properties.All(p => p.HasPublicSetter))
{
return;
}
var propertyChapter = _outputDocument.AddNewChapter("Properties");
IPrintableDocumentChapterStringContent paragraph =
propertyChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
paragraph.Content =
$"Contains all not settable properties in {_outputDocument.Title}.";
var propertyTable = propertyChapter.AddNewContent <IPrintableParagraphTable>();
propertyTable.WithHeaders("Property", "Description", "Condition");
foreach (var property in properties.Where(p => !p.HasPublicSetter))
{
propertyTable.WithRow(property.Name,
string.Join(" ", GetPropertySynopsisOrDescription(property)?.Content),
property.Condition);
}
}
/// <summary>
/// Appends a section to the documentation body containing all information about
/// the given targets. Therefore a table is created containing a row per target.
/// </summary>
/// <param name="targets">List of targets that should be represented by the section.</param>
private void AppendTargetSection(IList <IMsBuildTarget> targets)
{
if (targets.Count == 0)
{
return;
}
IPrintableDocumentChapter targetsChapter = _outputDocument.AddNewChapter("Targets");
IPrintableDocumentChapterStringContent paragraph =
targetsChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
paragraph.Content =
$"Contains all msbuild targets in {_outputDocument.Title}, ordered by name ascending.";
var propertyTable = targetsChapter.AddNewContent <IPrintableParagraphTable>();
propertyTable.WithHeaders("Target", "Description");
foreach (var target in targets.OrderBy(t => t.Name))
{
propertyTable.WithRow(CreateHyperlinkForTargetOverviewFile(target).Print(),
string.Join(" ", GetPropertySynopsisOrDescription(target)?.Content));
}
}
public void CreateElement_FromIFormattableDocumentChapterStringContent_ShouldReturnInstanceOfMarkdownChapterString()
{
MarkdownElementFactory factory = new MarkdownElementFactory();
IPrintableDocumentChapterStringContent chapterStringContent =
factory.CreateElement <IPrintableDocumentChapterStringContent>();
Assert.IsInstanceOfType(chapterStringContent, typeof(MarkdownChapterStringContent));
}
/// <summary>
/// Append a section to the documentation containing the targets description by using
/// the xml based help. Therefore the help section "Description" is used.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendDescriptionSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target)
{
if (!target.Help.ContainsSection(MsBuildHelpSections.Description, StringComparison.OrdinalIgnoreCase)
)
{
return;
}
string descriptionContent = target.Help.GetSectionContent(
MsBuildHelpSections.Description, StringComparison.OrdinalIgnoreCase
);
IPrintableDocumentChapter descriptionChapter = targetOverviewDocument.AddNewChapter("Description");
IPrintableDocumentChapterStringContent descriptionChapterContent =
descriptionChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
descriptionChapterContent.Content = string.Join(Environment.NewLine, descriptionContent);
}
/// <summary>
/// Append a section to the documentation containing the targets outputs by using the
/// xml based help. Therefore the help section "Outputs" is used.
/// </summary>
/// <param name="targetOverviewDocument">Document the section should be appended to.</param>
/// <param name="target">The target for which the section should be created.</param>
private void AppendOutputSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target)
{
if (!target.Help.ContainsSection(MsBuildHelpSections.Outputs,
StringComparison.OrdinalIgnoreCase))
{
return;
}
foreach (IMsBuildElementHelpParagraph outputsHelpParagraph in
target.Help.LookUp(MsBuildHelpSections.Outputs, StringComparison.OrdinalIgnoreCase))
{
IPrintableDocumentChapter parameterChapter =
targetOverviewDocument.AddNewChapter(
string.Format(CultureInfo.InvariantCulture, "Outputs {0}",
outputsHelpParagraph.Additional)
);
IPrintableDocumentChapterStringContent outputsSectionBody =
parameterChapter.AddNewContent <IPrintableDocumentChapterStringContent>();
outputsSectionBody.Content = outputsHelpParagraph.Content;
}
}
