private static void AppendSyntaxChart(string cmdletName, string setName, CmdletParameterSetPartitions parameterSetPartitioning, StringBuilder sb) { var isCustomNamedSet = !setName.Equals(CmdletParameterSetPartitions.AllSetsKey); var isDefaultSet = isCustomNamedSet && setName.Equals(parameterSetPartitioning.DefaultParameterSetName, StringComparison.Ordinal); var setParameterNames = parameterSetPartitioning.ParameterNamesForSet(setName, parameterSetPartitioning.HasNamedParameterSets); if (isCustomNamedSet) { sb.AppendFormat( isDefaultSet ? "<div class=\"paramsetname\"><h4>{0} (Default)</h4>" : "<div class=\"paramsetname\"><h4>{0}</h4>", setName); } sb.Append("<div class=\"syntaxblock\">"); // Microsoft cmdlets show params in syntax in defined but non-alpha order. Use the ordering we found // during reflection here in the hope the sdk has them in 'most important' order. Also, if there is // four or less params, keep the syntax on one line. sb.AppendFormat("<div class=\"cmdlet\">{0}</div>", cmdletName); var allParameters = parameterSetPartitioning.Parameters; var paramCount = setParameterNames.Count; if (paramCount > 0) { sb.Append("<div class=\"paramlist\">"); foreach (var p in allParameters) { if (!setParameterNames.Contains(p.CmdletParameterName)) { continue; } sb.AppendFormat("<div class=\"{0}\">-{1} <{2}></div>", paramCount < 5 ? "inlineParam" : "wrappedParam", p.CmdletParameterName, GetTypeDisplayName(p.PropertyType, false)); } sb.Append("</div>"); } sb.Append("</div>"); if (isCustomNamedSet) { sb.Append("</div>"); } }
private static void WriteSyntax(XmlWriter writer, string cmdletName, CmdletParameterSetPartitions parameterSetPartitioning) { writer.WriteStartElement("syntax"); if (parameterSetPartitioning.HasNamedParameterSets) { var sets = parameterSetPartitioning.NamedParameterSets; foreach (var set in sets) { WriteSyntaxItem(writer, cmdletName, set, parameterSetPartitioning); } } else { WriteSyntaxItem(writer, cmdletName, CmdletParameterSetPartitions.AllSetsKey, parameterSetPartitioning); } writer.WriteEndElement(); }
private static void WriteSyntax(CmdletPageWriter writer, string cmdletName, CmdletParameterSetPartitions parameterSetPartitioning) { var sb = new StringBuilder(); if (parameterSetPartitioning.HasNamedParameterSets) { var sets = parameterSetPartitioning.NamedParameterSets; foreach (var set in sets) { AppendSyntaxChart(cmdletName, set, parameterSetPartitioning, sb); } } else { AppendSyntaxChart(cmdletName, CmdletParameterSetPartitions.AllSetsKey, parameterSetPartitioning, sb); } writer.AddPageElement(CmdletPageWriter.SyntaxElementKey, sb.ToString()); }
protected override void GenerateHelper() { base.GenerateHelper(); if (string.IsNullOrEmpty(SDKHelpRoot)) { SDKHelpRoot = "http://docs.aws.amazon.com/sdkfornet/v3/apidocs/"; } else if (!SDKHelpRoot.EndsWith("/")) { SDKHelpRoot = SDKHelpRoot + "/"; } Console.WriteLine("Generating web help documentation:"); Console.WriteLine(".... SDK help base URI set to {0}", SDKHelpRoot); Console.WriteLine(".... writing doc output to {0}", OutputFolder); var buildLogsPath = Path.Combine(this.Options.RootPath, "logs"); if (!Directory.Exists(buildLogsPath)) { Directory.CreateDirectory(buildLogsPath); } var logFile = Path.Combine(buildLogsPath, Name + ".dll-WebHelp.log"); var oldWriter = Console.Out; try { using (var consoleWriter = new StreamWriter(File.OpenWrite(logFile))) { Console.SetOut(consoleWriter); CleanWebHelpOutputFolder(OutputFolder); CopyWebHelpStaticFiles(OutputFolder); CreateVersionInfoFile(Path.Combine(OutputFolder, "items")); var tocWriter = new TOCWriter(Options, OutputFolder); tocWriter.AddFixedSection(); Parallel.ForEach(CmdletTypes, (cmdletType) => { var(moduleName, serviceName) = DetermineCmdletServiceOwner(cmdletType); var cmdletInfo = InspectCmdletAttributes(cmdletType); string synopsis = null; if (cmdletInfo.AWSCmdletAttribute == null) { Console.WriteLine("Unable to find AWSCmdletAttribute for type " + cmdletType.FullName); } else { var cmdletReturnAttributeType = cmdletInfo.AWSCmdletAttribute.GetType(); synopsis = cmdletReturnAttributeType.GetProperty("Synopsis").GetValue(cmdletInfo.AWSCmdletAttribute, null) as string; } foreach (var cmdletAttribute in cmdletInfo.CmdletAttributes) { var typeDocumentation = DocumentationUtils.GetTypeDocumentation(cmdletType, AssemblyDocumentation); typeDocumentation = DocumentationUtils.FormatXMLForPowershell(typeDocumentation, true); Console.WriteLine($"Cmdlet = {cmdletType.FullName}"); Console.WriteLine($"Documentation = {typeDocumentation}"); var cmdletName = cmdletAttribute.VerbName + "-" + cmdletAttribute.NounName; var allProperties = GetRootSimpleProperties(cmdletType); var parameterPartitioning = new CmdletParameterSetPartitions(allProperties, cmdletAttribute.DefaultParameterSetName); var serviceAbbreviation = GetServiceAbbreviation(cmdletType); var cmdletPageWriter = new CmdletPageWriter(Options, OutputFolder, serviceName, moduleName, cmdletName); WriteDetails(cmdletPageWriter, typeDocumentation, synopsis, cmdletInfo.AWSCmdletAttribute); WriteSyntax(cmdletPageWriter, cmdletName, parameterPartitioning); WriteParameters(cmdletPageWriter, cmdletName, allProperties, false); WriteParameters(cmdletPageWriter, cmdletName, allProperties, true); WriteOutputs(cmdletPageWriter, cmdletInfo.AWSCmdletOutputAttributes); WriteNotes(cmdletPageWriter); WriteExamples(cmdletPageWriter, cmdletName); WriteRelatedLinks(cmdletPageWriter, serviceAbbreviation, cmdletName); cmdletPageWriter.Write(); lock (tocWriter) { var legacyAlias = InspectForLegacyAliasAttribution(moduleName, cmdletName, cmdletInfo.AWSCmdletAttribute); tocWriter.AddServiceCmdlet(moduleName, serviceName, cmdletName, cmdletPageWriter.GetTOCID(), synopsis, legacyAlias); } } }); tocWriter.Write(); WriteLegacyAliasesPage(); } } finally { Console.SetOut(oldWriter); } }
protected override void GenerateHelper() { Console.WriteLine("Generating Native PowerShell help (Get-Help) documentation file"); base.GenerateHelper(); var buildLogsPath = Path.Combine(this.Options.RootPath, "logs"); if (!Directory.Exists(buildLogsPath)) { Directory.CreateDirectory(buildLogsPath); } var logFilename = Path.Combine(buildLogsPath, Name + ".dll-Help.log"); var oldWriter = Console.Out; try { using (var consoleWriter = new StreamWriter(File.OpenWrite(logFilename))) { Console.SetOut(consoleWriter); var outputFile = Path.Combine(this.OutputFolder, Name + PsHelpFilenameTail); var settings = new XmlWriterSettings { Indent = true }; using (var psHelpWriter = new XmlTextWriter(outputFile, Encoding.UTF8)) { psHelpWriter.Formatting = Formatting.Indented; psHelpWriter.WriteStartElement("helpItems"); psHelpWriter.WriteAttributeString("schema", "maml"); Parallel.ForEach(CmdletTypes, (cmdletType) => { CmdletInfo cmdletInfo = InspectCmdletAttributes(cmdletType); using (StringWriter sectionWriter = new StringWriter()) using (var sectionXmlWriter = XmlWriter.Create(sectionWriter, new XmlWriterSettings() { OmitXmlDeclaration = true, ConformanceLevel = ConformanceLevel.Fragment, CloseOutput = true })) { string synopsis = null; if (cmdletInfo.AWSCmdletAttribute == null) { Console.WriteLine("Unable to find AWSCmdletAttribute for type " + cmdletType.FullName); } else { var cmdletReturnAttributeType = cmdletInfo.AWSCmdletAttribute.GetType(); synopsis = cmdletReturnAttributeType.GetProperty("Synopsis").GetValue(cmdletInfo.AWSCmdletAttribute, null) as string; } foreach (var cmdletAttribute in cmdletInfo.CmdletAttributes) { sectionXmlWriter.WriteStartElement("command"); sectionXmlWriter.WriteAttributeString("xmlns", "maml", null, "http://schemas.microsoft.com/maml/2004/10"); sectionXmlWriter.WriteAttributeString("xmlns", "command", null, "http://schemas.microsoft.com/maml/dev/command/2004/10"); sectionXmlWriter.WriteAttributeString("xmlns", "dev", null, "http://schemas.microsoft.com/maml/dev/2004/10"); { var typeDocumentation = DocumentationUtils.GetTypeDocumentation(cmdletType, AssemblyDocumentation); typeDocumentation = DocumentationUtils.FormatXMLForPowershell(typeDocumentation); Console.WriteLine($"Cmdlet = {cmdletType.FullName}"); Console.WriteLine($"Documentation = {typeDocumentation}"); var cmdletName = cmdletAttribute.VerbName + "-" + cmdletAttribute.NounName; var allProperties = GetRootSimpleProperties(cmdletType); var parameterPartitioning = new CmdletParameterSetPartitions(allProperties, cmdletAttribute.DefaultParameterSetName); var serviceAbbreviation = GetServiceAbbreviation(cmdletType); WriteDetails(sectionXmlWriter, cmdletAttribute, typeDocumentation, cmdletName, synopsis); WriteSyntax(sectionXmlWriter, cmdletName, parameterPartitioning); WriteParameters(sectionXmlWriter, cmdletName, allProperties); WriteReturnValues(sectionXmlWriter, cmdletInfo.AWSCmdletOutputAttributes); WriteRelatedLinks(sectionXmlWriter, serviceAbbreviation, cmdletName); WriteExamples(sectionXmlWriter, cmdletName); } sectionXmlWriter.WriteEndElement(); } sectionXmlWriter.Close(); lock (psHelpWriter) { psHelpWriter.WriteRaw(sectionWriter.ToString()); } } }); psHelpWriter.WriteEndElement(); } Console.WriteLine($"Verifying help file {outputFile} using XmlDocument..."); try { var document = new XmlDocument(); document.Load(outputFile); } catch (Exception e) { Logger.LogError(e, $"Error when loading file {outputFile} as XmlDocument"); } } } finally { Console.SetOut(oldWriter); } }
private static void WriteSyntaxItem(XmlWriter writer, string cmdletName, string setName, CmdletParameterSetPartitions parameterSetPartitioning) { var isCustomNamedSet = !setName.Equals(CmdletParameterSetPartitions.AllSetsKey); var isDefaultSet = isCustomNamedSet && setName.Equals(parameterSetPartitioning.DefaultParameterSetName, StringComparison.Ordinal); var setParameterNames = parameterSetPartitioning.ParameterNamesForSet(setName, parameterSetPartitioning.HasNamedParameterSets); writer.WriteStartElement("syntaxItem"); { writer.WriteElementString("name", cmdletName); var allParameters = parameterSetPartitioning.Parameters; // Microsoft cmdlets show params in syntax in defined but non-alpha order. Use the ordering we found // during reflection here in the hope the sdk has them in 'most important' order foreach (var parameter in allParameters) { if (!setParameterNames.Contains(parameter.CmdletParameterName)) { continue; } InspectParameter(parameter, out var isRequiredForParametersets, out var pipelineInput, out var position, out var aliases); var isRequiredForCurrentParameterset = isRequiredForParametersets != null && (isRequiredForParametersets.Count == 0 || isRequiredForParametersets.Contains(setName)); writer.WriteStartElement("parameter"); { writer.WriteAttributeString("required", isRequiredForCurrentParameterset.ToString()); writer.WriteAttributeString("variableLength", "false"); writer.WriteAttributeString("globbing", "false"); writer.WriteAttributeString("pipelineInput", pipelineInput); writer.WriteAttributeString("position", position); writer.WriteElementString("name", parameter.CmdletParameterName); writer.WriteStartElement("description"); { writer.WriteRawElementString("para", parameter.PowershellDocumentation); } writer.WriteEndElement(); writer.WriteStartElement("parameterValue"); { writer.WriteAttributeString("required", "true"); writer.WriteAttributeString("variableLength", "false"); writer.WriteString(parameter.PropertyTypeName); } writer.WriteEndElement(); } writer.WriteEndElement(); } } writer.WriteEndElement(); }
protected override void GenerateHelper() { Console.WriteLine("Generating Native PowerShell help (Get-Help) documentation file"); base.GenerateHelper(); var buildLogsPath = Path.Combine(this.Options.RootPath, "logs"); if (!Directory.Exists(buildLogsPath)) { Directory.CreateDirectory(buildLogsPath); } var logFilename = Path.Combine(buildLogsPath, Name + ".dll-Help.log"); var oldWriter = Console.Out; try { using (var consoleWriter = new StreamWriter(File.OpenWrite(logFilename))) { Console.SetOut(consoleWriter); var outputFile = Path.Combine(this.OutputFolder, Name + PsHelpFilenameTail); var settings = new XmlWriterSettings { Indent = true }; using (var psHelpWriter = new XmlTextWriter(outputFile, Encoding.UTF8)) { psHelpWriter.Formatting = Formatting.Indented; psHelpWriter.WriteStartElement("helpItems"); psHelpWriter.WriteAttributeString("schema", "maml"); foreach (var cmdletType in CmdletTypes) { InspectCmdletAttributes(cmdletType); string synopsis = null; if (AWSCmdletAttribute == null) { Console.WriteLine("Unable to find AWSCmdletAttribute for type " + cmdletType.FullName); } else { var cmdletReturnAttributeType = AWSCmdletAttribute.GetType(); synopsis = cmdletReturnAttributeType.GetProperty("Synopsis").GetValue(AWSCmdletAttribute, null) as string; } foreach (var cmdletAttribute in CmdletAttributes) { psHelpWriter.WriteStartElement("command"); psHelpWriter.WriteAttributeString("xmlns", "maml", null, "http://schemas.microsoft.com/maml/2004/10"); psHelpWriter.WriteAttributeString("xmlns", "command", null, "http://schemas.microsoft.com/maml/dev/command/2004/10"); psHelpWriter.WriteAttributeString("xmlns", "dev", null, "http://schemas.microsoft.com/maml/dev/2004/10"); { var hasDynamicParams = DynamicParamsType.IsAssignableFrom(cmdletType); var typeDocumentation = DocumentationUtils.GetTypeDocumentation(cmdletType, AssemblyDocumentation); typeDocumentation = DocumentationUtils.FormatXMLForPowershell(typeDocumentation); Console.WriteLine("Cmdlet = {0}", cmdletType.FullName); if (hasDynamicParams) { Console.WriteLine("This cmdlet has dynamic parameters!"); } Console.WriteLine("Documentation = {0}", typeDocumentation); var cmdletName = cmdletAttribute.VerbName + "-" + cmdletAttribute.NounName; var allProperties = GetRootSimpleProperties(cmdletType); var parameterPartitioning = new CmdletParameterSetPartitions(allProperties, cmdletAttribute.DefaultParameterSetName); var serviceAbbreviation = GetServiceAbbreviation(cmdletType); WriteDetails(psHelpWriter, cmdletAttribute, typeDocumentation, cmdletName, synopsis); WriteSyntax(psHelpWriter, cmdletName, parameterPartitioning); WriteParameters(psHelpWriter, cmdletName, allProperties); WriteReturnValues(psHelpWriter, AWSCmdletOutputAttributes); WriteRelatedLinks(psHelpWriter, serviceAbbreviation, cmdletName); WriteExamples(psHelpWriter, cmdletName); } psHelpWriter.WriteEndElement(); } } psHelpWriter.WriteEndElement(); } Console.WriteLine("Verifying help file {0} using XmlDocument...", outputFile); try { var document = new XmlDocument(); document.Load(outputFile); } catch (Exception e) { Logger.LogError(e, "Error when loading file {0} as XmlDocument", outputFile); } } } finally { Console.SetOut(oldWriter); } }