public static void WriteMarkdowns(IEnumerable <VariantGroup> variantGroups, PsModuleHelpInfo moduleHelpInfo, string docsFolder, string examplesFolder)
{
Directory.CreateDirectory(docsFolder);
var markdownInfos = variantGroups.Where(vg => !vg.IsInternal).Select(vg => new MarkdownHelpInfo(vg, examplesFolder)).OrderBy(mhi => mhi.CmdletName).ToArray();
foreach (var markdownInfo in markdownInfos)
{
var sb = new StringBuilder();
sb.Append(markdownInfo.ToHelpMetadataOutput());
sb.Append($"# {markdownInfo.CmdletName}{Environment.NewLine}{Environment.NewLine}");
sb.Append($"## SYNOPSIS{Environment.NewLine}{markdownInfo.Synopsis.ToDescriptionFormat()}{Environment.NewLine}{Environment.NewLine}");
sb.Append($"## SYNTAX{Environment.NewLine}{Environment.NewLine}");
var hasMultipleParameterSets = markdownInfo.SyntaxInfos.Length > 1;
foreach (var syntaxInfo in markdownInfo.SyntaxInfos)
{
sb.Append(syntaxInfo.ToHelpSyntaxOutput(hasMultipleParameterSets));
}
sb.Append($"## DESCRIPTION{Environment.NewLine}{markdownInfo.Description.ToDescriptionFormat()}{Environment.NewLine}{Environment.NewLine}");
sb.Append($"## EXAMPLES{Environment.NewLine}{Environment.NewLine}");
foreach (var exampleInfo in markdownInfo.Examples)
{
sb.Append(exampleInfo.ToHelpExampleOutput());
}
sb.Append($"## PARAMETERS{Environment.NewLine}{Environment.NewLine}");
foreach (var parameter in markdownInfo.Parameters)
{
sb.Append(parameter.ToHelpParameterOutput());
}
if (markdownInfo.SupportsShouldProcess)
{
foreach (var parameter in SupportsShouldProcessParameters)
{
sb.Append(parameter.ToHelpParameterOutput());
}
}
sb.Append($"### CommonParameters{Environment.NewLine}This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).{Environment.NewLine}{Environment.NewLine}");
sb.Append($"## INPUTS{Environment.NewLine}{Environment.NewLine}");
foreach (var input in markdownInfo.Inputs)
{
sb.Append($"### {input}{Environment.NewLine}{Environment.NewLine}");
}
sb.Append($"## OUTPUTS{Environment.NewLine}{Environment.NewLine}");
foreach (var output in markdownInfo.Outputs)
{
sb.Append($"### {output}{Environment.NewLine}{Environment.NewLine}");
}
sb.Append($"## NOTES{Environment.NewLine}{Environment.NewLine}");
sb.Append($"ALIASES{Environment.NewLine}{Environment.NewLine}");
foreach (var alias in markdownInfo.Aliases)
{
sb.Append($"{alias}{Environment.NewLine}{Environment.NewLine}");
}
if (markdownInfo.ComplexInterfaceInfos.Any())
{
sb.Append($"{ComplexParameterHeader}{Environment.NewLine}");
}
foreach (var complexInterfaceInfo in markdownInfo.ComplexInterfaceInfos)
{
sb.Append($"{complexInterfaceInfo.ToNoteOutput(includeDashes: true, includeBackticks: true)}{Environment.NewLine}{Environment.NewLine}");
}
sb.Append($"## RELATED LINKS{Environment.NewLine}{Environment.NewLine}");
foreach (var relatedLink in markdownInfo.RelatedLinks)
{
sb.Append($"{relatedLink}{Environment.NewLine}{Environment.NewLine}");
}
File.WriteAllText(Path.Combine(docsFolder, $"{markdownInfo.CmdletName}.md"), sb.ToString());
}
WriteModulePage(moduleHelpInfo, markdownInfos, docsFolder);
}
public static ModulePageMetadataOutput ToModulePageMetadataOutput(this PsModuleHelpInfo moduleInfo) => new ModulePageMetadataOutput(moduleInfo);
protected override void ProcessRecord()
{
try
{
var variants = GetModuleCmdletsAndHelpInfo(this, ModulePath).SelectMany(ci => ci.ToVariants()).Where(v => !v.IsDoNotExport).ToArray();
var allProfiles = variants.SelectMany(v => v.Profiles).Distinct().ToArray();
var profileGroups = allProfiles.Any()
? variants
.SelectMany(v => (v.Profiles.Any() ? v.Profiles : allProfiles).Select(p => (profile: p, variant: v)))
.GroupBy(pv => pv.profile)
.Select(pvg => new ProfileGroup(pvg.Select(pv => pv.variant).ToArray(), pvg.Key))
: new[] { new ProfileGroup(variants) };
var variantGroups = profileGroups.SelectMany(pg => pg.Variants
.GroupBy(v => new { v.CmdletName, v.IsInternal })
.Select(vg => new VariantGroup(ModuleName, vg.Key.CmdletName, vg.Select(v => v).ToArray(),
Path.Combine(vg.Key.IsInternal ? InternalFolder : ExportsFolder, pg.ProfileFolder), pg.ProfileName, isInternal: vg.Key.IsInternal)))
.ToArray();
var license = new StringBuilder();
license.Append(@"
# ----------------------------------------------------------------------------------
#
# Copyright Microsoft Corporation
# Licensed under the Apache License, Version 2.0 (the ""License"");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an ""AS IS"" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ----------------------------------------------------------------------------------
");
HashSet <string> LicenseSet = new HashSet <string>();
foreach (var variantGroup in variantGroups)
{
var parameterGroups = variantGroup.ParameterGroups.ToList();
var isValidProfile = !String.IsNullOrEmpty(variantGroup.ProfileName) && variantGroup.ProfileName != NoProfiles;
var examplesFolder = isValidProfile ? Path.Combine(ExamplesFolder, variantGroup.ProfileName) : ExamplesFolder;
var markdownInfo = new MarkdownHelpInfo(variantGroup, examplesFolder);
List <PsHelpExampleInfo> examples = new List <PsHelpExampleInfo>();
foreach (var it in markdownInfo.Examples)
{
examples.Add(it);
}
variantGroup.HelpInfo.Examples = examples.ToArray();
var sb = new StringBuilder();
sb.Append($"{Environment.NewLine}");
sb.Append(variantGroup.ToHelpCommentOutput());
sb.Append($"function {variantGroup.CmdletName} {{{Environment.NewLine}");
sb.Append(variantGroup.Aliases.ToAliasOutput());
sb.Append(variantGroup.OutputTypes.ToOutputTypeOutput());
sb.Append(variantGroup.ToCmdletBindingOutput());
sb.Append(variantGroup.ProfileName.ToProfileOutput());
sb.Append("param(");
sb.Append($"{(parameterGroups.Any() ? Environment.NewLine : String.Empty)}");
foreach (var parameterGroup in parameterGroups)
{
var parameters = parameterGroup.HasAllVariants ? parameterGroup.Parameters.Take(1) : parameterGroup.Parameters;
parameters = parameters.Where(p => !p.IsHidden());
if (!parameters.Any())
{
continue;
}
foreach (var parameter in parameters)
{
sb.Append(parameter.ToParameterOutput(variantGroup.HasMultipleVariants, parameterGroup.HasAllVariants));
}
sb.Append(parameterGroup.Aliases.ToAliasOutput(true));
sb.Append(parameterGroup.HasValidateNotNull.ToValidateNotNullOutput());
sb.Append(parameterGroup.HasAllowEmptyArray.ToAllowEmptyArray());
sb.Append(parameterGroup.CompleterInfo.ToArgumentCompleterOutput());
sb.Append(parameterGroup.OrderCategory.ToParameterCategoryOutput());
sb.Append(parameterGroup.InfoAttribute.ToInfoOutput(parameterGroup.ParameterType));
sb.Append(parameterGroup.ToDefaultInfoOutput());
sb.Append(parameterGroup.ParameterType.ToParameterTypeOutput());
sb.Append(parameterGroup.Description.ToParameterDescriptionOutput());
sb.Append(parameterGroup.ParameterName.ToParameterNameOutput(parameterGroups.IndexOf(parameterGroup) == parameterGroups.Count - 1));
}
sb.Append($"){Environment.NewLine}{Environment.NewLine}");
sb.Append(variantGroup.ToBeginOutput());
sb.Append(variantGroup.ToProcessOutput());
sb.Append(variantGroup.ToEndOutput());
sb.Append($"}}{Environment.NewLine}");
Directory.CreateDirectory(variantGroup.OutputFolder);
File.WriteAllText(variantGroup.FilePath, license.ToString());
File.AppendAllText(variantGroup.FilePath, sb.ToString());
if (!LicenseSet.Contains(Path.Combine(variantGroup.OutputFolder, "ProxyCmdletDefinitions.ps1")))
{
// only add license in the header
File.AppendAllText(Path.Combine(variantGroup.OutputFolder, "ProxyCmdletDefinitions.ps1"), license.ToString());
LicenseSet.Add(Path.Combine(variantGroup.OutputFolder, "ProxyCmdletDefinitions.ps1"));
}
File.AppendAllText(Path.Combine(variantGroup.OutputFolder, "ProxyCmdletDefinitions.ps1"), sb.ToString());
}
if (!ExcludeDocs)
{
var moduleInfo = new PsModuleHelpInfo(ModuleName, ModuleGuid, ModuleDescription);
foreach (var variantGroupsByProfile in variantGroups.GroupBy(vg => vg.ProfileName))
{
var profileName = variantGroupsByProfile.Key;
var isValidProfile = !String.IsNullOrEmpty(profileName) && profileName != NoProfiles;
var docsFolder = isValidProfile ? Path.Combine(DocsFolder, profileName) : DocsFolder;
var examplesFolder = isValidProfile ? Path.Combine(ExamplesFolder, profileName) : ExamplesFolder;
WriteMarkdowns(variantGroupsByProfile, moduleInfo, docsFolder, examplesFolder);
}
}
}
catch (Exception ee)
{
Console.WriteLine($"${ee.GetType().Name}/{ee.StackTrace}");
throw ee;
}
}
public ModulePageMetadataOutput(PsModuleHelpInfo moduleInfo)
{
ModuleInfo = moduleInfo;
}