/// <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)); } }
/// <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> /// 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 examples by using the /// xml based help. Therefore all examples are appended a code block. /// </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 AppendExampleSection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target) { if (target.Help.ContainsSection(MsBuildHelpSections.Example, StringComparison.OrdinalIgnoreCase) == false) { return; } foreach (IMsBuildElementHelpParagraph exampleHelpParagraph in target.Help.LookUp( MsBuildHelpSections.Example, StringComparison.OrdinalIgnoreCase)) { IPrintableDocumentChapter exampleChapter = targetOverviewDocument.AddNewChapter(MsBuildHelpSections.Example); IPrintableDocumentCodeBlock exampleCodeBlock = exampleChapter.AddNewContent <IPrintableDocumentCodeBlock>(); var codeBlock = MsBuildElementHelpCodeBlockUtility.Parse(exampleHelpParagraph.Content); exampleCodeBlock.AppendContentLine(codeBlock.Content); exampleCodeBlock.SetLanguage(codeBlock.Language.ToString()); } }
/// <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; } }
/// <summary> /// Append a section to the documentation containing the targets dependencies by using the /// MsBuild target attributes. Therefore all dependencies like "AfterTargets", "BeforeTargets" /// and "DependsOnTargets" are appended as a paragraph table. /// </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 AppendDependencySection(IPrintableDocument targetOverviewDocument, IMsBuildTarget target) { if (target.HasTargetDependencies == false) { return; } IPrintableDocumentChapter dependencyChapter = targetOverviewDocument.AddNewChapter("Target Dependencies"); IPrintableParagraphTable dependencyTable = dependencyChapter.AddNewContent <IPrintableParagraphTable>() .WithHeaders("Target", "Dependency Type", "Dependency Description"); foreach (var dependentOnTarget in target.DependsOnTargets) { dependencyTable.WithRow(dependentOnTarget, "DependsOnTargets", string.Format(CultureInfo.InvariantCulture, "Calls the target {0} before execution of {1}.", dependentOnTarget, target.Name)); } foreach (var afterTarget in target.AfterTargets) { dependencyTable.WithRow(afterTarget, "AfterTargets", string.Format(CultureInfo.InvariantCulture, "Runs the target {0} after the execution of {1} has finished.", target.Name, afterTarget)); } foreach (var beforeTargets in target.BeforeTargets) { dependencyTable.WithRow(beforeTargets, "BeforeTargets", string.Format(CultureInfo.InvariantCulture, "Runs the target {0} before the execution of {1} starts.", target.Name, beforeTargets)); } }