Ejemplo n.º 1
0
        /// <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));
            }
        }
Ejemplo n.º 2
0
        /// <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();
        }
Ejemplo n.º 3
0
        /// <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);
        }
Ejemplo n.º 4
0
        /// <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());
            }
        }
Ejemplo n.º 5
0
        /// <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;
            }
        }
Ejemplo n.º 6
0
        /// <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));
            }
        }